Well, there is an article on 13 Tips to Comment Your Code. A well written piece of article, indeed. In the article there are a lot of good advices on how to comment your code so that other people can get the most out of your program.
Here I would like to offer the One Single Tip on code comments. This tip is the aggregation of my software development experience, so hopefully it could be useful to others.
Ready? Here it is the One Single Tip:
Let your code document itself!
Yup, the only true documentation, my friend, is your source code and nothing else. XML documentation, or any other form of documentation, although sounds great in theory, but nevertheless in practice they don't work. Why? Because they are simply not a part of the executables.
You see, we developers are very busy, and we abhor paperwork. Documentation sounds so second-class that if you assign a junior developer to write XML documentation for his senior, he will surely give you a blank stare. Not just that, code changes, everyday. When bugs come in, you need to modify your code to get it removed. When requests come in, you need to upgrade your program to implement the new features. When your code is broken, either your program won't compile or your tests won't pass.
But when bugs come in, you don't need to modify the comments; changing the comments is useless anyway, it won't get you an inch closer to your solution. When there are new feature requests, you can still left the comments intact with no effect on the implementation whatsoever. And when your comments are broken, or outdated, or are simply, downright wrong, your program can still run happily and your tests can still pass.
This is why comments are, hmm--I hate to say this because it is going to alienate a lot of documentation tools providers-- redundant. Instead of relying on comments to convey your intention, why not let your code--be it the production code or test code-- shows what your module does exactly?
Instead of writing a lot of comments to explain the subtle behaviors of your program, why not restructure your logics so that they are self-evident? Instead of documenting what a method is doing, why not choose a clear name for that method? Instead of tagging your code to indicate unfinished work, why not just throw an NotImplementedException()? Instead of worrying whether your comments sound polite enough to your boss, your colleagues or anyone reading the code, why not just stop worrying by not writing them at all?
The clearer your code is, the easier it is to maintain it, to extend it, to work on it on future editions. The less ordorous is your code, the less need there is to comment it. The more the comments, the higher the maintanence cost.
There is one qualification to my points, however. I am writing this assuming that you are not developing your next generation quantitative model that allows you to short and long derivatives with 100% success rate.
If you have a brilliant algorithm, or you have come up with a superb mathematical model that describes the Secret of Universe but no one has heard of it yet, then of course you need to document it. But this type of documentation is very far from the concepts we associated with our source code documentation.
To properly document your algorithm, you should
Follow up Post: Comment on Why? Why?
Here I would like to offer the One Single Tip on code comments. This tip is the aggregation of my software development experience, so hopefully it could be useful to others.
Ready? Here it is the One Single Tip:
Let your code document itself!
Yup, the only true documentation, my friend, is your source code and nothing else. XML documentation, or any other form of documentation, although sounds great in theory, but nevertheless in practice they don't work. Why? Because they are simply not a part of the executables.
You see, we developers are very busy, and we abhor paperwork. Documentation sounds so second-class that if you assign a junior developer to write XML documentation for his senior, he will surely give you a blank stare. Not just that, code changes, everyday. When bugs come in, you need to modify your code to get it removed. When requests come in, you need to upgrade your program to implement the new features. When your code is broken, either your program won't compile or your tests won't pass.
But when bugs come in, you don't need to modify the comments; changing the comments is useless anyway, it won't get you an inch closer to your solution. When there are new feature requests, you can still left the comments intact with no effect on the implementation whatsoever. And when your comments are broken, or outdated, or are simply, downright wrong, your program can still run happily and your tests can still pass.
This is why comments are, hmm--I hate to say this because it is going to alienate a lot of documentation tools providers-- redundant. Instead of relying on comments to convey your intention, why not let your code--be it the production code or test code-- shows what your module does exactly?
Instead of writing a lot of comments to explain the subtle behaviors of your program, why not restructure your logics so that they are self-evident? Instead of documenting what a method is doing, why not choose a clear name for that method? Instead of tagging your code to indicate unfinished work, why not just throw an NotImplementedException()? Instead of worrying whether your comments sound polite enough to your boss, your colleagues or anyone reading the code, why not just stop worrying by not writing them at all?
The clearer your code is, the easier it is to maintain it, to extend it, to work on it on future editions. The less ordorous is your code, the less need there is to comment it. The more the comments, the higher the maintanence cost.
There is one qualification to my points, however. I am writing this assuming that you are not developing your next generation quantitative model that allows you to short and long derivatives with 100% success rate.
If you have a brilliant algorithm, or you have come up with a superb mathematical model that describes the Secret of Universe but no one has heard of it yet, then of course you need to document it. But this type of documentation is very far from the concepts we associated with our source code documentation.
To properly document your algorithm, you should
- Write it in Microsoft Word
- Type in all the mathematical symbols
- Polish it into an accepted format
- Send it for peer review and for publication purpose
- Refer to the paper in your XML documentation
Follow up Post: Comment on Why? Why?
