Chapter 9 -- Commenting Code

[Previous] [Next]

Chapter 9

Have you ever purchased an item requiring some assembly, such as a bicycle, only to find that the instruction manual was missing from the box? It's bad enough trying to assemble an item when you actually have the often less-than -adequate instructions. ( Why does slot A in the picture look like it's on Part C, not Part D? Is this drawing to scale? That scribbling could be one of three different bolts. Argh!) Trying to follow a procedure written without comments can be as difficult as putting together a bicycle without instructions. Trying to understand complicated or lengthy code without comments can be like trying to put together a bicycle blindfolded!

If you've ever had to revisit your own uncommented code after a year or so, you've almost assuredly started commenting your code since then. There are simply no good reasons for not commenting your code. Comments make code easier to understand and easier to follow. Good comments guide the reader through the twists and turns of your application like a good blueprint, explaining the expected results and possible exceptions to the desired outcome. If you give your variables and procedures good, descriptive names (as detailed in Chapter 6, "Variables"), much of your code becomes self-documenting . However, you still need comments. For the most part, it's hard to have too many comments, but it is possible to have ineffective comments. You must understand and apply all the different types of comments correctly to ensure that your code can be understood by other developers ”or by you when you revisit the code.

A common excuse programmers give for not writing comments is that they take too much time to write. In reality, it doesn't take much time at all to comment as you write code. Some developers say that some of their procedures are difficult to comment. A good rule of thumb is that if a section of code is hard to comment, it's even harder for someone else to understand without comments. Tricky, hard-to-comment code is probably bad code. If you find yourself having a difficult time documenting all or part of a procedure, step back and take a good look at the code; you'll probably find a better approach.

Creating the right mix of different types of comments can be challenging because each procedure poses a unique set of considerations. But by following the guidelines in this chapter, you'll be able to improve your commenting noticeably.

Goals of Using Code Comments

---

Your goals when using code comments should include

• Documenting the purpose of the code (the why, not the how )
• Clearly indicating the thinking and logic behind the code
• Calling attention to important turning points in the code
• Reducing the need for readers to run a simulation of code execution in their heads