I am all for comments in code (gasp I know) but some are just a total waste of time.
Case in point. I came across this today.
/// Commit Transaction.
public void CommitTransaction()
WTF, I guess putting the Commit Transaction comment makes it more clear that the method "CommitTransaction' commits a transaction.
As I said above, I am for comments, but I have a few simple rules I like to follow.
- Don't repeat yourself
Like the example above don't waste my time telling me via a comment what the method/property name does when the name of the method/comment clearly states that information.
- Comment intent, not logic
I know how to read if statements, and for loops. Please do not tell me 'doing a look' or 'doing a check' because that is clear from the code. However, please tell me why you are doing the loop if it is not obvious. If there is some funky logic in the loop, that I need to know.
- Keep it short, and 'timeless'
I do not want to read a novel. I want to read 1 maybe 2 sentences and know enough to move on.
- If it is a 'Hack' it needs to be stated as such
We all have added 'Hacks' to our code. These are things that would not make sense to the casual observer but there is a reason why they are being done. THESE MUST BE COMMENTED because if they are not someone else in the future is going to come along and repeat all your mistakes.
Ok, rant over.
Till next time,
BTW, I removed that comment from my code base.
09-29-2008 3:40 PM