Benefits Of Header Comments

Given that many development organizations have been using file, class and function/procedure/subroutine/method comments since such things existed, it seems likely that there must be some rational reason why they thought it was worthwhile to do so.

The cost/benefit trade-offs may have changed since then, or be different in your development environment: Knowing the benefits and costs, and alternatives that provide the desired information, can help one make more sensible business decisions about what to do, and what to avoid.

[To a large extent, this is likely to be a StrawMan Argument, as most of this community (quite sensibly) favors elimination of unnecessary maintenance work, as waste. But let's at least make an honest attempt at listing potential benefits, however small, of this practice, so that they can be compared to the actual costs.]

NOTE: This page is nothing but StrawMan arguments. No attempt has been made to promote actual reasons why certain tracking information may be valuable if contained as straight prose text in the comment header of a file. Perhaps some kind Wikizen will correct that deficiency in this page.
Claim: "I need all this information in the source files because I need it when we're working with the software offline, with printouts."

Benefits: Alternatives:
Claim: "I need to see the file name of this printout."

Alternatives:
Claim: "I need these comments to produce technical documentation with this automated tool." (IE: JavaDoc)

Benefits: Alternatives:
Claim: "I need to know who originally created this file."

Benefits: Alternatives:
Claim: "I need to know the history of changes to this file - who changed it, when and why."

Alternatives:
Claim: "I need a visual marker, in the printout, to separate different parts of the program - to mark the beginning of each class, method or function, for instance."

Alternatives:
Claim: "I need to put a Copyright message in each file."

Benefits: Comments:
Claim: "I need to put my email address in each and every file so that people can contact me."

Alternatives:
Claim: "It makes people feel good, that we have a well-defined corporate standard for this. We have it under control."

Alternatives:
Actual usage: The design has been done to show how services are implemented in the architecture. All of the interfaces between services and objects have been identified (as best as can be done) and the code is ready for implementation.

The implementation in code is described in the headers and source files where the code resides. Each object is described in its context, its storage is identified, and both public and private methods are described in brief.

Each non-trivial method is described in its own doc block prior to the method itself. Anything out of the ordinary is explained in detail, but the doc block is mostly for describing the algorithm followed in the method.

Alternatives: Whatever you want to find that works better. Don't whine about this until you come up with something, though.
See: BigBlocksOfAsterisks, FileHeaders

CategoryDocumentation

EditText of this page (last edited August 21, 2010) or FindPage with title or text search