Comments In Code(hamedh.posterous.com)
hamedh.posterous.com
Comments In Code
http://hamedh.posterous.com/comments-in-code
9 comments
I signed up for an account just to say I strongly disagree with this. I'm a sys admin who doesn't spend all day writing code, and certainly doesn't know all the common idioms associated with different languages. Leaving a comment about in the code about something that's not obvious to some one who doesn't code in perl/ruby/php (or whatever you're using) but if familiar with common programming concepts is beyond useful to someone like me.
Why I comment:
When I'm learning a language I write comments for myself. Notes about syntax, idioms, gotchas, and whatever else.
When I'm fixing a problem I leave XXX markers around to easily keep track of what I'm doing.
When I'm writing maintenance code I reference the ticket number, describe the problem or feature, and why we implemented the fix or feature the way we did.
You should never see the first two types of comments in checked in code, but I bet that I've probably saved later maintenance programmers hours of frustration with that last type of comment.
When I'm learning a language I write comments for myself. Notes about syntax, idioms, gotchas, and whatever else.
When I'm fixing a problem I leave XXX markers around to easily keep track of what I'm doing.
When I'm writing maintenance code I reference the ticket number, describe the problem or feature, and why we implemented the fix or feature the way we did.
You should never see the first two types of comments in checked in code, but I bet that I've probably saved later maintenance programmers hours of frustration with that last type of comment.
I'll just leave this here:
http://zachholman.com/posts/documentation/
Yea, good post, I agree that documentation is key.
Comments and readable code aren't mutually exclusive.
> Code should be almost as readable as a book. You should be to read without pausing too much as well as skimming.
I pause much more reading code than I do reading prose.
Trying to keep a lookup table of functions and variables in my head is much harder than reading a few lines of prose to let me know what's going on.
Comments should summarise what's going on, so that when you have a bug, you can jump to the right section to change.
> Comments are almost like an annotation in a book. So use them sparingly.
The way I think of it: Don't use comments to annotate your code. Use code to annotate your comments.
> Code should be almost as readable as a book. You should be to read without pausing too much as well as skimming.
I pause much more reading code than I do reading prose.
Trying to keep a lookup table of functions and variables in my head is much harder than reading a few lines of prose to let me know what's going on.
Comments should summarise what's going on, so that when you have a bug, you can jump to the right section to change.
> Comments are almost like an annotation in a book. So use them sparingly.
The way I think of it: Don't use comments to annotate your code. Use code to annotate your comments.
I agree - it is the old principle of least surprise. You should use comments when the code reader would be surprised...
Sometimes you have to do bad stuff and you should stick a comment in there so that when you come back to that bit in code you are forewarned...
Think of it as hic seunt leones on old maps (here be lions for all the non-latin speakers out there...)
Sometimes you have to do bad stuff and you should stick a comment in there so that when you come back to that bit in code you are forewarned...
Think of it as hic seunt leones on old maps (here be lions for all the non-latin speakers out there...)
Don't like my comments in my code? Don't read 'em. They're useful to some people.
This discussion is one that will never die because people will always have entrenched, dogmatic viewpoints on this. I dislike comments that explain what you're doing. The code should be readable enough to see what you're doing. However having spent over a decade now maintaining code written by people that may not be with the organization anymore, it's always nice to occasionally get context on WHY someone wrote the code they did. Odd bugs and subsequent workarounds, weird client requirements, etc. I've spent many hours trying to figure out why someone did something because they're not around anymore to ask. We can go on and on about the purity of code and how readable it should be but no amount of concise code can replace "did this because of client requirement X,Y and Z" right there so I don't have to go hunting to find out. The gulf between how things SHOULD be and how they ACTUALLY are is pretty wide in my experience.
I think parent's import point is that comments should document WHY you are doing something. The code itself should easily convey the WHAT and HOW.
"Programs must be written for people to read, and only incidentally for machines to execute." - http://mitpress.mit.edu/sicp/front/node3.html
"Programs must be written for people to read, and only incidentally for machines to execute." - http://mitpress.mit.edu/sicp/front/node3.html