Removing Comments

I also agree with commenting intent, but maybe not with some of the "removal" suggestions herein.

My company has actually seen significant gains in coding speed, acclimation time, and code quality after adopting the Commenting Showing Intent standard, wherein every logical block/statement has an intent comment, mandatory. If someone went through and "boyscouted" our code, it would do serious damage to our code base, and probably get them banned. ;)

Take, for example, that bug you mentioned finding because of the comment. Yes, you might have found that on your own, but keep in mind the sheer MASS of code you're looking at. Usually, by time one encounters that, their eyes have already glazed over. What stops them? The discrepancy between the comment and the code. It encourages further investigation, and has led to a LOT of bugs being caught and fixed, even by complete newbies to the language/code.

Thus...while one should definitely prune bad comments, I'd say a better thing to do would be to tidy the comments up.

• Make sure they're commenting intent, not "what" or "how" (unless you're explaining an especially bizarre algorithmic choice or whatnot).

• Check for discrepancies, and after resolving them, ensure the comments are accurate.

• Remove cruft.

• Fix grammar (it's more important than it sounds).

In other words, just make it more readable. But PLEASE don't go "boyscouting" in CSI-standardized code!

I'm torn on this, too. Your example of "unsubscribedFilter" is ambiguous without either the comment or reinforcement from the similarly-used "duplicateFilter". If it was on its own I would probably interpret it as a filter which only let unsubscribed items through, not one which filtered them out.

The better solution for me would be to change the filter or method names and then remove the comments - which is too much change for this "boyscouting" idea.

I know what you're saying, and I know it might seem that I'm being picky, but I'm saying this to back up my point, which is that even if you think something is clear without comments, it might not be to someone else. It might be a good idea to ask the person at the next desk whether they agree with you that something's obvious.

Would you say this comment is justified?

  buffer(length: number) {
    // has to come first so we don't allocate on error
    const start = this.fwd(length)
    const newBuf = Buffer.allocUnsafe(length)
    this.buf.copy(newBuf, 0, start, this.pointer)
    return newBuf
  }

It's there to prevent someone "optimizing" this method to the following:

  buffer(length: number) {
    const newBuf = Buffer.allocUnsafe(length)
    this.buf.copy(newBuf, 0, this.fwd(length), this.pointer)
    return newBuf
  }

Which offers no performance improvement, but if an error causes the bombardment of this method with yuuuuuge numbers, orders of magnitude larger than the underlying Buffer, it will cause lag, instead of just throwing the errors nicely.

For reference, this is what the .fwd method does:

  /**
   * Sets the buffer pointer, the address at which next parse will begin.
   * @throws {RangeError} if this will put pointer outside of `0..=len` range.
   * @param {number} addr What index to go to
   * @returns {number} the previous pointer, before setting
   */
  private goTo(addr: number): number {
    const { pointer, len } = this
    const newPointer = addr
    if (newPointer > len) throw new RangeError("Index past Buffer end")
    if (newPointer < 0) throw new RangeError("Index before Buffer beginning")
    this.pointer = newPointer
    return pointer
  }
  /**
   * Increments the buffer pointer, the address at which next parse will begin.
   * @throws {RangeError} if this will put pointer outside of `0..=len` range.
   * @param {number} dist How far to wind the buffer pointer. Can be negative to rewind and overwrite.
   * @returns {number} the previous pointer, before winding
   */
  fwd(dist: number): number {
    return this.goTo(this.pointer + dist)
  }

The JSDoc might seem excessive, but it is useful because tooling displays it in tooltips wherever it is referenced.

Nice article Jason.

If anyone is looking to delve deeper into proper coding techniques then I suggest you pick up "Clean Code" by Robert Martin (Uncle Bob). It's a fantastic read and will help you think in a more concise thought process when writing code.

I'm kind of torn on this issue.

First of all, I like the code itself to be self-documenting with no inline comments. Comments that describe implementation, such as the "stop looping" one you mentioned, can quickly go out of date.

However, in C# components and microservices, I use documentation comments to allow other developers to see Intellisense hints in Visual Studio and to build documentation files using tools like Sandcastle. These comments should describe what the method does, such as "Search for unpaid invoices for specified customer", but not go into any implementation details like "Query XYZ.Invoices database table for unpaid customer invoices".

Also, since I frequently deal with legacy code going back 20+ years in some cases, I want to keep comments made by programmers who left the company many years ago. This gives me insight into what they were thinking when they originally developed the code. I may add my own comments (initialed) to indicate that the comments are no longer applicable if that's the case.