There are a multitude of blog posts out there that detail when you should and should not comment, but Jeff Atwood of Coding Horror puts it best:
Code can only tell you how the program works; comments can tell you why it works. Try not to shortchange your fellow developers in either area.
We’ve all heard of tales of college students whose professors required that they extensively document their code; sometimes at risk of a letter grade.
Once upon a time, in a land not so far away, a diligent young computer science student sat eagerly attentive in her C++ programming class. Her formidable instructor was droning on and on about how Programming Comments were the basis of all that is good in the world of software design. Then at last, those famous words, “If you do not comment your code, you will automatically drop one (1) letter grade.”
Academia is one thing, but what about programming texts? Shouldn’t they advocate the sane way of commenting code?
I wish.
I pulled open my old C++ book today, just to get a refresher on function pointers and things I’d forgotten (since C# makes use of function pointers in anonymous methods and lambda expressions), and happened to open up to the page on comments.
There were no less than eight bullet points on commenting code. From Structured & Object-Oriented Problem Solving using C++, Third Edition by Andrew C. Staugaard:
Debugging Tip
Programming Comments are an important part of the program documentation and should be used liberally (emphasis mine). […] At a minimum, the program should include the following comments:
- The beginning of the program should be commented with the programmer’s name, date the program was written, date the program was last revised, and the name of the person doing the revision.
- The beginning of the program should be commented to explain the purpose of the program, which includes the problem definition and program algorithms. This provides an overall perspective by which anyone, including you, can begin debugging or maintaining the program.
- Preprocessor directives should be commented as to their purpose.
- Constant and variable definitions should be commented as to their purpose.
- Major sections of the program should be commented to explin the overall purpose of the respective section.
- Individual program lines should be commented when the purpose of the code is not obvious relative to the application.
- All major subprograms (functions in C++) should be commented just like the main program function.
- The end of each program block (right curly brace) should be commented to indicate what the brace is ending.
Well, at least he’s thorough. Some of the advice is sage; and other parts of the advice are just downright redundant in the real world, if you’re using source control and an anything but notepad.
So here’s my revised list — directed at that very same college student who is stuck reading that text.
Debugging Tip
Program Comments are an important part of the program documentation and should be used to help any programmer understand what is happening. […] Use the following guidelines for guidance:
- The beginning of the program should be commented with the programmer’s name, date the program was written, date the program was last revised, and the name of the person doing the revision.
- The beginning of the program should be commented to explain the purpose of the program, which includes the problem definition and program algorithms. This provides an overall perspective by which anyone, including you, can begin debugging or maintaining the program.
- Preprocessor directives should be commented as to their purpose, and directives should not change the meaning of reserved words.
- Constant and Variable definitions should have a clear name that explains their purpose, so comments aren’t necessary.
- Major sections of the program should be commented to explain the overall purpose of the respective section when its purpose isn’t reasonbly clear.
- All major subprograms (functions in C++) should be commented just like the main program function.
- The end of each program block (right curly brace) should be commented to indicate what the brace is ending.
- Write code that explains itself. Comments should only be used to tell someone WHY you did something, not what you did. That’s what code is for.
Instead of using the beginning of the textbook to discuss basics that any CS101 book should cover, I’d use it to cover source control, and the integral part it plays in keeping track of code changes — something that the author wanted the bullet points to do, but which don’t make sense in modern source control systems.
If you have new developers on your team, do them (and yourself) a favor and point them to one of the references I mentioned. Friends don’t let friends comment liberally!
NB: These ideas aren’t original to me; I got them from reading Coding Horror and reading Code Complete.