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
Some prefer brevity:Listing 2
And here's another way:Listing 3
All of the above ways are valid, depending on the complexity of
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