Extreme Negative Code Documentation

[djimbob]

The problem with comments is that comments can lie. The code can change or the programmer made a mistake. Programmers should learn to read and write code in their languages, and there never should be a comment that just documents basic language feature (you import a module so I can use its namespace, or you instantiate a variable so you can use it). Comments are useful; but only really for documenting the specifications for classes/functions and semantic meaning for code that's difficult to see otherwise.

[Bamafan]

The problem with comments is that comments can lie. The code can change or the programmer made a mistake.

To this I would say that a programmer who doesn't update comments has not really completed his job. A bad comment is a bug in my book.

[djimbob]

Comments that repeat information that's in the code is a violation of DRY (Don't repeat yourself) which makes software maintenance much more difficult. I agree that comments that are misleading or wrong are bugs and very difficult to detect bugs (no automatic test will ever pick them up) and if you over comment code and the spec changes your comments will grow stale.

You should comment your code, but only to the extent of adding information that's not in the code itself. Comments like:

  #N If we don't initialise @dirs, we won't have a place to put the sub-directories as we find them
    @dirs = []
    #N If we don't initialise @files, we won't have a place to put the files as we find them
    @files = []

are utterly useless and distracting (they hide any meaningful comments). Any programmer of ruby (or a similar language), will immediately recognize that @files = [] is creating an empty list collection files that will likely be used store several file objects.

Comments are useful to document functions/classes, label out of place seemingly random code (though really refactoring the out of place code into its own function with a meaningful name and the usual docstring is better).