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:

• Code reviews can be done in conference rooms, away from the "work area."
• One can examine and mark up code away from the "work area" - at home, in conference rooms, outside under a tree, etc.

Alternatives:

• Include the necessary information in printouts:
  • Use a decent file printer that includes the information you need in headers, footers and borders:
    • Path & File Name
    • Date and Time last changed
    • Line Numbers
    • Page Numbers
    • Line Annotations showing last Change Request Number that changed each line
    • etc...
  • Print additional files and listings showing information not included in the source code:
    • Differences between this and the previous version.
    • Source Control Version History.
    • External technical documentation (if there is any)
• Work with the software online, with an InteractiveDevelopmentEnvironment?. This will enable automation of tasks that are tedious and error prone to do by hand, with printouts.
• Use a portable computer, such as a laptop.
• Use a shared PC and projector, in conference rooms.

---

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

Alternatives:

• Use a file printer that includes the file name (and other relevant information) in the header or footer of each page.
• Use coding conventions that make the file name obvious from the file's content:
  • Name files the same as the classes they contain.
    • (In Java, the path to the file must match its package, and the file name must match the public class name in the file. So the path and file name should be obvious - unless there are too many file and class header comments getting in the way. ;-)

---

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

Benefits:

• If the documentation is a product deliverable, then this is needed.
• If the documentation contains useful information and is actually used, then this practice is worthwhile.

Alternatives:

• Improve the names of the classes, methods and parameters so that less additional hand-written and hand-maintained technical documentation is needed.
• Avoid redundant documentation for code that is only used by developers who have full and easy access to the source code they are using.

---

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

Benefits:

• They may be the only person who understands this program and its requirements.

Alternatives:

• Insist that code be written so that multiple people can understand it. In other words, it should be minimally maintainable.
• Encourage team members to work closely with each other, so that more than one person knows what's going on.
  • Try PairProgramming.
• Get this information from your source control system.

---

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

Alternatives:

• Get this information from your source control system.

---

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:

• Break up excessively large files into smaller files - one per class, for instance.
  • When individual classes are too large, refactor functionality out into helper classes (stored in separate files!).

• Get a better code editor:
  • Syntax-based color coding can usually solve this problem.
  • Ability to expand and contract comment headers and method bodies helps.
  • Having a visual "outline" of classes and methods, with two-way navigation between the code and the outline helps.

---

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

Benefits:

• Protects ownership rights.
• Required by some Licenses (BSD, GPL, etc.)

Comments:

• This one may be needed. Consult your legal department for expert advice.
  • Ask them if they Copyright message needs to be in the compiled code too.
  • Ask them about the use of "(C)" in the Copyright message.
    • (If they say that you should use it, then you are talking to the wrong people; they're feeding you bad information.)

---

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

Alternatives:

• Put it in one place, so that when it changes you don't have to change every source file you've ever touched.

---

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

Alternatives:

• GetOverIt.
• Write better software, then you really will have it under control.

---

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