Today’s Daily WTF is about code commenting where the comment describes what the code does. What’s wrong with that? First of all, code should be self describing as much as possible. Keep your code well structured and as simple as possible, use declarative variable and method names so it can be read and understood without any explaining comments. This is possible with most code, except some really tricky algorithm implementations which will be easier to read with some guiding comments. I usually find it valuable in these cases to add a full example with some values showing how the algorithm transforms these values, step by step.
So does that mean I don’t comment my code? Not at all, I comment a lot. But I try to add comments that instead of explaining what the code does, instead explains why it does it. You should assume that anyone reading your code understands the language, so you don’t need to explain that part of the program for them. For example, this is an example of an unnecessary comment:
m_nRow++; // Increase m_nRow with 1.
Instead, here’s a more useful comment:
m_nRow++; // m_nRow comes from a zero based index and this class assumes that first row is row number one and not zero.
Instead of describing what to do we describe why we do it. Programmers who don’t get the increment operator should not be let near your code anyway.
Another useful place for comments is to help programmers see hard to spot pitfalls when doing changes to the code. When writing code we always do tradeoffs because of workload or deadlines and usually our classes are highly specialized for its precise purpose. There are usually a lot of cases that are not handled, since these cases can not occur. However, when someone later changes the code, these cases just might be something that suddenly is not just theoretical problems. A common example is of course threading, that your class is not threadsafe since its not used by more than one thread, but later this is changed and no one know that your class wasn’t threadsafe.
So our code comments should serve three purposes: explain why the code is how it is, point out pitfalls and finally explain difficult code parts. Out of these, the two first comment types are the most common.
Comments can serve one more purpose, and that is when changing other programmer’s code. I usually add comments to other’s code before changing it. This way forces me to really go through the code and understand it before I attempt to change it. I usually read it while debugging it to make sure it works as I think it does. The commenting forces me to express my understanding of the code in words which will make it very obvious if I understand it or not. It’s hard to write a descriptive comment about something you don’t get. The better a program is structured; the easier it is to write comments for it and of course, the opposite is true as well. But after adding the comments I comprehend the code better than if I just had read it.
