DEV Community

loading...

Discussion on: Removing Comments

Collapse
gonedark profile image
Jason McCreary Author

I don't consider "doc blocks" to be comments. So I wouldn't consider those "excessive".

As far as the inline comment regarding the optimization, these are definitely the gray area where a comment does relay non-obvious implementation details. This could potentially be mitigated with a name such as optimizedBuffer or by pushing the buffer optimizations lower to a createFastBuffer.

Collapse
qm3ster profile image
Mihail Malo • Edited

I didn't mean the JSDoc as part of the question, it was just a literal copy paste to show what fwd does.
I don't see how it could be extracted ergonomically, since the invariant is that this.fwd(length) returning as the return value and this.pointer the two arguments to copy runs before allocate

In most cases inlining them is perfectly acceptable. These are the cases around buffer:

  doublele() {
    return this.buf.readDoubleLE(this.fwd(8))
  }
  slice(length: number) {
    return this.buf.slice(this.fwd(length), this.pointer)
  }
  buffer(/**/){/**/}
  string(length: number, encoding: Encoding) {
    return this.buf.toString(encoding, this.fwd(length), this.pointer)
  }

But yeah, hopefully this class will be single-responsibility enough that no one will come edit it at all. And the comment is definitely staying.

One more good thing about deleting comments is that the few that do remain are seen as that much more important.

Forem Open with the Forem app