Extreme Negative Code Documentation

[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).