2/9/2010 12:32 AM
Well, from the schoolage we've been taught that commenting code is good, and must be done as much as possible. But with the appearance of Refactoring an idea arised that comments are evil and commenting is like applying air freshener to our bad-smelling code.
On the other hand it's true that code should be self-descripting. The names of class members and local variables should tell us what the code actually does and how it does it. And, Yes, well-written code does answer the questions "What?" and "How?". BUT (!) the code cannot tell us WHY he is doing things particularly that way.
Imagine we have the following code (taken from the real-world project):
private void updateParameters()
// Update of parameters may break sorting
Here we clearly see what's going on. But one question arises: why do we use BeginSort() and EndSort() methods here? The commented line answers the question.
Did I exonerate comments? Not at all. The best solution is to have tests (NUnit or whatever else) that cover each and every line of code explaining why is it needed. If you have not enough time/power for tests, then write comments.