I first realized I sucked at commenting code when I was going back to old project and found complete classes and methods uncommented, knowing what the code did wasn't as hard but why it did it.
So now I always write a short comment about how and why it does it. It is more for my own sake than for others.
The first time someone else used my code and asked how to use a particular method. It's the point when you realise that you don't understand your own code.
I recently had to go back to an old project (from 2 years ago) and I realised that I had commented too much!
The comments were often not helpful and cluttered up the source. Shame on me...
Commenting code is a tricky business. The most common problems related to commenting is in my opinion excessive commenting and bad code. You should aim for your code the be self-documenting by using appropriate method names, variable names and data structures that make sense. If you fail to do this, you might find yourself over commenting to make up for your poor coding.
The time I relooked some GPS analysis code where single character variables were used... At the time, the code was soooo obvious. Of coarsee "d" is distance, "lt" is latitude....
Since then, I have greatly increased my variable readability
I'm still lousy. Even when your code is commented, others will still have trouble understanding it. So I don't bother. This seems to raise the heckles of other programmers and management, but I stick to my guns. It's nearly always a waste of time.
Thankfully, I'm also blessed with a very good memory, so I nearly always remember how I coded a project. This means I can communicate to others how a piece of code works (which is quicker anyway). And if I'm unavailable, they can work it out for themselves, which they would have to do anyway, with or without comments.
And since I can touch type, long meaningful variable and function names more than make up for it.
For example:
function FetchNextCharacterFromBuffer() {
}
Hmm, I wonder what this function does. Who needs comments?
I rule at commenting code!
Or I just haven't realised I'm lousy at it yet..
Yesterday actually. I've read through "When NOT to comment code" and realized, that I was overusing comments there, where proper coding itself would of be better.
When do I realize my commenting style sucks?
When reading my old code (old meaning written 6 months or more ago).
But isn't this a very subjective question? Can there be a right answer?
Simple write clean code, no comments needed!
Use readable names for classes, methods, variables. Write tests showing the functionality. Do one clear thing in a method. No side effects.
In high school when I lost a programming competition and a judge provided a response to the effect of: "Though by far the technically superior program, the lack of documentation prohibited the award of top placement."
My code was completely devoid of comments. I came in third. My savings bond would've been $750 larger had I dropped a few comments in there...