Basic commenting

This series of articles on developerWorks comprises a complete guide to better programming in Perl. In this second installment, Teodor dissects comments in code. The comments in a program's code are perhaps as important to the long-range goals of a software team as the actual code itself. Unfortunately, they are also often the most neglected. Through tips, quips, examples, and anecdotes, Teodor takes an in-depth look at the imperative nature of commenting a program's language from beginning to end.

There is no such thing as too much documentation. Being clear often means repeating yourself. Think of your code as something you present to the world. There are a lot of people in the world. The one comment you thought was redundant could make someone's day. It could even be your day, five years from now, when you are adding a new feature.

Use good planning when writing your programs. You don't have to determine every detail in advance, but you should break up the program into component parts, and use comments to fill in the gaps.

The following is my personal coding style. You may not like it, but try to look at it objectively and see what you can use for yourself or for your team.

First of all, think of the intended audience for the comments. Try to make the comments clear enough for a third-party consultant to follow. The more complex the code, the more comments you should add to clarify intent. Don't leave comments for later; make them a part of your thought process: problem, solution, comment, then debug. Especially important is creating comments before debugging. The comments in your own code will help you debug better and faster.

It is helpful sometimes to state not only the solution to the problem, but also the problem itself. For example:

# function: do_hosts
#
# purpose: to process every host in the /etc/hosts table and see if it
# resolves to a valid IP
#
# solution: read the list of hosts as keys in a hash, then go through
# the list of keys (hosts) and store the IP address for each host as
# the value for that key, or undef() if it doesn't resolve properly.
# Return a reference to the hash, or undef if the /etc/hosts file was
# not accessible.

Some prefer brevity:

# function: do_hosts:  process every host in the /etc/hosts table and see if it
# resolves to a valid IP; return a reference to the hash (key=host,
# value=IP or undef), or undef if the /etc/hosts file was not accessible. 

And here's another way:

# do_hosts: returns a ref to hash of hosts (key=host, value=IP/undef)
# from /etc/hosts 

All of the above ways are valid, depending on the complexity of do_hosts(). If the function is two lines, don't waste your time writing three paragraphs of comments. If it's several pages, however, don't be frugal with explanations.