[jandrese]

It takes many years for people to figure out what the right level of commenting is. It's more of an art than a science. Worse, the level of comments depends on the reader. An old veteran may find one distracting that a beginner finds extremely helpful. But they can also be a liability if they aren't maintained with the code or if they make statements about other code that fails to be true after awhile.

A comment like:

# Add 1 to the length of this buffer to work around an off by 1 error in this function in library foo

Can quickly go stale, but sometimes not and could otherwise be accidentally reverted by someone who notices that the buffer is 1 element too long for no apparent reason.

A better comment:

# Add 1 to the length of this buffer to work around an off by 1 error in function foo from library bar (version 1.7.3b circa Nov 1997)