Developer Forums | About Us | Site Map


Useful Lists

Web Host
site hosted by netplex

Online Manuals

Road to better programming: Chapter 2. Commenting your code
By Teodor Zlatanov - 2004-02-11 Page:  1 2 3 4 5 6 7 8

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:

Listing 1

# 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:

Listing 2

# 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:

Listing 3

# 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.

View Road to better programming: Chapter 2. Commenting your code Discussion

Page:  1 2 3 4 5 6 7 8 Next Page: Commenting the beginning of the program

First published by IBM developerWorks

Copyright 2004-2017 All rights reserved.
Article copyright and all rights retained by the author.