Comment, Comment, Comment, and Comment

[Previous] [Next]

One day, my friend François Poulin, who was working full time on maintaining some code someone else wrote, came in wearing a button that said, "Code as if whoever maintains your code is a violent psychopath who knows where you live." François is by no means a psychopath, but he did have a very good point. Although you might think your code is the model of clarity and completely obvious, without correct comments, your code is as bad as raw assembly language to the maintenance developers. The irony is that the maintenance developer for your code can easily turn out to be you! Remember François's button every time you write a line of code.

Our job as engineers is twofold: develop a solution for the user and make that solution maintainable for the future. The only way to make your code maintainable is to comment it. By "comment it," I don't mean simply writing comments that duplicate what the code is doing; I mean documenting your assumptions, your approach, and your reasons for choosing the approach you did. You also need to keep your comments coordinated with the code. Normally mild-mannered maintenance programmers can turn into raving lunatics when they're trying to update code that does something different from what the comments say it's supposed to do.

I use the following approach to commenting:

  • Each function or method needs a sentence or two that clarifies the following information:
    • What the routine does
    • What assumptions the routine makes
    • What each input parameter is expected to contain
    • What each output parameter is expected to contain on success and failure
    • Each possible return value

  • Each part of the function that isn't completely obvious from the code needs a sentence or two that explains what it's doing.
  • Any interesting algorithm deserves a complete description.
  • Any nontrivial bugs you've fixed in the code need to be commented with the bug number and a description of what you fixed.
  • Well-placed trace statements, assertions, and good naming conventions can also serve as good comments and provide excellent context to the code.
  • Comment as if you were going to be the one maintaining the code in five years.
  • If you find yourself saying, "This is a big hack" or "This is really tricky stuff," you probably need to rewrite the function instead of commenting it.

Proper and complete documentation in the code marks the difference between a serious, professional developer and someone who is playing at it. Donald Knuth once observed that you should be able to read a well-written program just as you read a well-written book. Although I don't see myself curling up by the fire with a copy of the TeX source code, I strongly agree with Dr. Knuth's sentiment.

I recommend that you study "Self-Documenting Code," Chapter 19 of Steve McConnell's phenomenal book Code Complete (Microsoft Press, 1993). Reading this chapter is how I learned to write comments. If you comment correctly, even if your maintenance programmer turns out to be a psychopath, you know you'll be safe.



Debugging Applications
Debugging Applications for MicrosoftВ® .NET and Microsoft WindowsВ® (Pro-Developer)
ISBN: 0735615365
EAN: 2147483647
Year: 2000
Pages: 122
Authors: John Robbins

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net