Jeff has a good post here about code comments and that they shouldn’t be used as crutches:
I agree with the article, but one thing I rarely hear mentioned is that it’s often more interesting to comment the business justification than it is to comment the code. Jeff goes some way towards suggesting this when he says to comment the “why”, but for many people that translates to “Why did I write the code this way?”.
I often find that code I’m maintaining is missing comments regarding the business logic. Rather than “Why is the code designed like this?”, something like “Why is the business process designed like this?”
This becomes most useful when you look at unfamiliar code (your own, probably) and decide that the easily-digestible code is nevertheless doing something you are sure is silly, and you change it. Big mistake.
Example of a code architecture comment:
Example of a business architecture comment:
All are useful, but I find the second type are rarely used. They become more valuable as the code ages.