There are some fundamental differences between a program's internal and external documentation. Internal documentation--that is, comments--should give a close explanation of specific things within the code, while external documents are needed to give context to the program itself.

Internal documentation serves a basic function: it helps people more quickly and easily understand the code. This is accomplished in a number of ways, like labeling the condition that ends a loop. But the most important thing internal documentation can do is to help someone understand why a particular piece of code is there in the first place. This is essentially to provide your reasoning. It is is to tell someone what you were thinking. While I can find out for myself why an "if" statement ends, I can't understand why you decided to structure the if statement THAT way and not another way.

Thus, you need to tell me this. Comments that accomplish this should answer the following questions:

• What does this piece do?
• Why is it here?
• How does it work?
• What does it rely on?
• What does it produce?
• How is this design unique?

Within the code, each of these items should be included for each method, operation, function, file or object that does not implicitly supply this information already. There isn't a universal rule about where to put these: whether they should be header comments or inline. Instead, you must be critical of your code and look for those places that a reader may not understand.

These will be unique or not commonly found or used elements, elements that are written differently than they normally would be, elements that are essential to the correct outcome, or on which other items are connected or depend.

One tip that is normally made in most programming manuals is "don't overcomment," but this is really too subjective of a rule to follow. What is too many comments? We're probably each going to have different ideas of overcommenting. So, the best suggestion I can make is to drop this tip completely: don't follow it or even consider it. Instead, look for situations like the above where a comment is needed. You may find that it's every line that needs a comment--and if the code is good (effective, clear and efficient)--then there's nothing wrong with that.

Another tip that's often made is "don't comment obvious code." This is another way too subjective tip to follow with any confidence. What's obvious? If we have different training or expertise, we'll have different ideas of elements that are or should be obvious: but they might not be obvious to everyone. So again, drop this tip and just critically analyze your code. It takes time, sure, but the payoff (which might not be for five years), is much more rewarding.

Of secondary importance are things like revision history, the name of the person who created or last changed the item, etc. These elements, and not those in the paragraph above, are the items normally highlighted in programming manuals, but these items are useless if the reader doesn't understand why the code is there in the first place or even what it does.

This internal documentation, if it supplies the information I suggest above, will create autogenerated documentation that is actually valuable to someone, because it will answer their questions.

External documentation is normally a simple text file that is included with the code files. The text file should be a recording, of sorts, of the complete life story of the program: 

• What does this program do?
• What is the output?
• What is the input?
• What does it depend on?
• Who created it?
• Why was it created?
• When was it created?
• What problems were encountered when creating it?
• What was not completed?
• What areas were difficult or demanded creative (that is, unusual) solutions?
• What are the future plans?

External documentation is important for helping people more quickly understand a program. Researchers have found that reading cognition is aided, and quickened, by elements other than the writing itself. Knowing who wrote a document, what the document is about, the title of the document and the other items stemming from the above questions creates for a reader a cognitive framework before even reading the document. Once readers enter the document (after creating this mental framework), understanding the document comes much more quickly. This occurs with both natural language documents AND source code.

In both cases, it is important to always keep the comments updated and timely, and ensure they are correct. If changes are made to the code, the same changes should be made to the documentation: otherwise documentation becomes useless. Further, clean house at every opportunity: delete outdated, wrong or incomplete documentation. Especially for internal documentation: don't comment out code you "plan on coming back to" or can't complete. Just get rid of it. If you want a record, include it in the external doc. Otherwise, the only comments you should include in the code are the relevant explanations for future readers.

For technical, professional and business communication help in the Las Cruces, NM area, visit Lanier Infomedia. 

Last update: 27-03-2009 13:42