Slashdot Log In
Successful Strategies for Commenting Your Code
Posted by
Hemos
on Mon Aug 01, 2005 11:49 AM
from the good-things-to-learn dept.
from the good-things-to-learn dept.
LilG writes "Over at Particletree, Ryan Campbell writes about Successful Strategies for Commenting Your Code. His essay gives advice and examples on proper commenting, and details some different strategies."
This discussion has been archived.
No new comments can be posted.
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
Full
Abbreviated
Hidden
Loading... please wait.
Huh? (Score:5, Funny)
Re:Huh? (Score:3, Funny)
Was that some form of early DMCA or IP lockdown?
Re:Huh? (Score:3, Funny)
Obfucksucated code contest (Score:3, Funny)
Re:Huh? (Score:5, Funny)
*ducks*
Parent
My favorite code comment not written by me (Score:5, Funny)
Re:My favorite code comment not written by me (Score:5, Funny)
I was in a similar spot a month or two ago and found some other company's comments - unhelpful as always - in the form of typed out sound effects.
# This function goes vroooooooommm-pop!
I have no idea why the developers put such comments there other than to entertain themselves as they sifted through their horribly written Perl.
Parent
Re:My favorite code comment not written by me (Score:5, Interesting)
Parent
What makes a good Comment? (Score:5, Interesting)
a) What you're doing.
b) Why you're doing it.
c) How you're doing it.
I took three assembly programming classes in College. The last one was on the 68k, where we wrote an embedded OS.
Assembly code isn't all that intuitive, and writing comments is especially important. Our professor allocated 20% of our grade on each lab to comments. In addition to accurately describing what we were doing, he checked our grammar. One thing he always stressed is that too many engineers these days don't know how to write comments. Grammar is important in getting the message across unambiguously.
In general, if a person can read your comment and then figure out how to translate what you said into code, then your comment is pretty good. It should give an idea of what you're trying to do, why you're doing it, and how you're doing it.
One of my professor's grad students translated a program from MACRO32 into C++, and all without even knowing MACRO32. He looked through the comments to figure out what they were doing. They were so specific that he could easily translate blocks of code over to C++.
Comments are very important - and I should definitely comment MY code. I can't remember the number of times I've come back to code that I've written and thought "WTF am I doing here? WTF was I smoking when I wrote this?!"
Parent
Re:What makes a good Comment? (Score:3, Interesting)
I call B.S. ALL Engineers KNOW how to write comments. If they don't know how to comment they're code they aren't an Engineer. In fact I will lay odds the 60% of the "Software Engineers" out there aren't really Engineers. Just because you have a degree in Computer Science doesn't make you an Engineer. I know plenty of "Software Engineers" who don't know what an ABET accredited engineering program is.
All
Re:What makes a good Comment? (Score:5, Insightful)
As long as you're commenting the _real_ effect of the instruction, and not just mindlessly repeating what the mnemonic already tells the reader. I've seen lots of stupid assembly-language comments like "increments the A register". Gee, thanks - I couldn't have figured that out from the "INC A" mnemonic.
Parent
Re:What makes a good Comment? (Score:3, Insightful)
Re:What makes a good Comment? (Score:4, Informative)
Or worse yet, lying.
One pre-paleolithic piece of mainframe assembler I (and my colleagues) once worked with was an intricate sequence of shift operations designed to isolate a 5-bit segment in the middle of a 36-bit word in one of the accumulators. It was documented with a breathtakingly detailed block of comments, complete with little pictures of the contents of the register at each step in the process (composed of dashes and vertical bars and everything--ASCII documentation art).
The code wasn't working, but there was absolutely no way that it was the code's fault. It was just FM (F'ing Magic) that it was broke. We were convinced of this. That is, until one of my supervisors, a crusty old communications sergeant, actually studied the instruction string of the segement of code in question and noticed that in the last step, the actual answer was being shifted the wrong direction--right out of the register and into the bit bucket.
If only we could have compiled the comments...
This, then, is Johnson's Postulate on Documentation: "Read the source code, too."
Parent
Re:What makes a good Comment? (Score:3, Insightful)
Not specifically regarding assembler, but you've just reminded me of the thing I absolutely hate the most which is people taking a chunk of existing code, comments an' all, tweaking the code to do something similar but different, but not updating the comments. Any typically the people (they ain't programmers!) who do this also use the existing function name but suffix it with a "2" or something -- I mean, why bother with a meaningful name? Someone might be able to understand the code!
it was hard to write (Score:2)
but not really, commenting as you go has always worked best for me, going off an uncommented API is evil when it is complex, i loathe working on some projects because there is absolutly no documentation
Gotta say it (Score:2, Funny)
Example (Score:4, Funny)
No (Score:5, Funny)
This loop starts at 1, and to 5 it counts. It doesn't count to 6, nor it does count to 8. It does not count to 3 or 4, except in passage to 5. When it reaches number 5, the fifth number...
Parent
Re:No (Score:4, Funny)
Parent
var names (Score:3, Insightful)
Practice what you preach (Score:5, Funny)
Comments are more important than Code? (Score:5, Funny)
I once tried writing code that was completely made up of comments. It was easy to write and all, but didn't work very well.
Re:Comments are more important than Code? (Score:5, Funny)
Parent
Re:Comments are more important than Code? (Score:5, Interesting)
By front-loading the process with comments, I find it really helps not just the maintainability but it also keeps my programming tasks on track.
Parent
Don't comment (Score:5, Funny)
http://www.cenqua.com/commentator/ [cenqua.com]
I was skeptical at first regarding the topic (Score:5, Insightful)
I think it was Fowler who once went as far as to state that when you find yourself needing to document code in order for it to be understood (vs. thoroughness, completness, or document generation) you probably need to refactor your code.
How many times have we come across code like this?
public void bigFunction1()...
public void bigFunction2()...
Re:I was skeptical at first regarding the topic (Score:3, Insightful)
Commenting (Score:5, Insightful)
And for crying out loud update the comments when you change code!
*grumbles about 10 year old code and 15 year old comments*
Re:Commenting (Score:4, Insightful)
Parent
really being stressed in schools (Score:3, Informative)
What's So Hard About Comments... (Score:3, Interesting)
A comment on comments (Score:5, Insightful)
The following is an example of useless documentation:
frobWoggleFfloofMoing
public void frobWoggleFfloofMoing(String, String, String)
...
You see, running Doxygen over your header files may produce some output in HTML format, but it doesn't produce what I like to call "documentation." For instance, documentation would explain what is a Woggle, and when should it be Frobbed?
Thank you, and have a nice life.
My commenting habits (Score:3, Interesting)
Why I comment code... (Score:5, Interesting)
Things to always remember when commenting (Score:4, Funny)
2. Use randomly chosen variable names, or objects that resemble your favorite Orcs and Trolls from LotR - after all, everyone knows that a Lothlorien object will have farseeing ability, so it's obvious.
3. When instantiating something for the first time, never explain it - real programmers read the original object source.
4. If you do something complex, write a short pithy comment like
5. If you do something easy but you were drinking too much hot cocoa, write a long verbose description, and also mention how good the hot cocoa was.
6. Always include song lyrics to what you're listening to while you wrote the code.
7. Object inheritence means never having to explain the code.
8. Repetition is the best way to reinforce obvious things - so repeat the obvious thing since it's the best way to reinforce it.
9. If you break up with your girl/boyfriend, write about it in the comments - people really want to know.
10. If you're updating or modifying code, write your opinion about the original code in the comments. Use nasty words if you can.
Re:Things to always remember when commenting (Score:3, Funny)
All Depends... (Score:4, Funny)
# The main function starts here
or...
# This is a loop and it will run while a certain
# condition exists.
or...
# Don't forget to remove this section after
# I'm gone - Dan - 04/25/1995
Think about the children! ;P
How & Whys (Score:4, Insightful)
Comment the why, not the how.
Hopefully the code should be clear enough to pick out the how, but *why* you are doing something is never going to be apparent from the code itself - at best someone might be able to infer it, but that becomes especially tricky when time passes or a new person signs on.
My take (Score:3, Interesting)
Anyway, this is the strategy I've come up with after having to go over my old code.
zerg (Score:5, Insightful)
Next on his list of things to write about (Score:3, Funny)
Literate Programming (Score:3, Interesting)
Two words: Literate Programming [wikipedia.org]
Comments: Why, Sometimes What, Never How (Score:3, Interesting)
1. Use comments liberally to explain why. Why would I want to call this method? Why did you choose this particular algorithm? Why are you ignoring this exception? Source code has very little support for explaining why without comments - and why is often both the most important point and the most easily forgotten.
2. Use comments occasionally to explain what. Your method names, parameter names, and logic should strive to be clear enough that explaining what is happening is unnecessary. But that is in a perfect world. If you can't make it clear in a reasonable amount of time, add a comment explaining what is happening.
3. Never use comments to explain how. The real how diverges from the comment too quickly. If someone needs to see how, they should look at the source code, which is the only reliable resource for explaining how.
There are exceptions to all of these I'm sure, and this doesn't cover everything (for example, the above says nothing parameter definition comments or copyright comments), but they're decent rules of thumb for most cases.
Flip the Script (Score:3, Interesting)
This discipline is tied to my code layout style. I put braces ('{' and '}') each on their own line, in languages which use them to delimit blocks of code (most of the languages I use). After the opening brace, I put a single space, then a comment, like:
# Use list if it has items.
if($numEntries = $#list)
{ # Get personal info from people in the list.
Then I indent the block with 4 spaces, starting with a comment, like:
# Use local storage.
my(@names, @addresses, @jobTitles, $name, $address, $jobTitle);
Loops get described as a single operation, but their block describes each iteration's operation:
# Get columns into separate lists.
foreach $row (@list)
{ # Add fields to their columns.
# Get fields from row.
($name, $address, $jobTitle) =
($row =~
# Store fields in their columns.
push(@names, $name);
push(@addresses, $address);
push(@jobTitles, $jobTitle);
} # each row
} # Used list of people.
The comments, layout and variable names make it easy to understand what's happening. So easy that it's useful to read them first, then write the code
Re:Flip the Script (Score:3, Interesting)
It wasn't terrible, but the result was a lot of comments that were echos of the code, and an unknowable amount of code that should have been broken out into discrete functions, but was instead kept nearby its comment because the commen
Re:indeed (Score:3, Interesting)
Comments should be common sense and used where the developer thinks it is appropriate and where they will aid future developers/maintainers understand a particular block of code. Nothing more, nothing less. The article is just typical PHB management bullshit and I feel dumber after reading it.
The scenario that is the ultimate end product to "comment standardisation" is what happened at a company that a friend of mine works for. They had a developer sit there for 3 days, go t
Re:indeed (Score:3, Informative)
The first is that common sense isn't. There are lots of coders who seem not to have any.
Second, what seems clear and obvious when you're writing the code is anything but to someone else who's approaching the code fresh. That "someone else" may very well be you six months or a year down the road. Every function over one line (and most of those) should have a comment indicating what it does. Any variable that isn't a throwaway loop counter or similar should either be so cl
Re:Don't do it! (Score:3, Insightful)
Don't EVER comment your code if you work for a company. That's a sure fire way to lose your job! If you don't comment your code then you are the only person who can understand it, making you indispensible.
Great idea! The myth of indispensibility is a great reason. May your next job be as a maintenance programmer in a Perl shop where the previous "indispensible" developer had his ass fired for threatening the boss and you get 50,000 lines of Perl dumped in your lap.
Re:Don't do it! (Score:4, Informative)
1. You are likely to be passed by on promotions because self inflicted developer dependence for this application.
2. You will have to figure it out later, after you've forgotten what all that magic gobly-gook does.
magic gobly-gook: effective, efficient, and incredibly dense code produced wilst 'in the zone'
Parent
Re:Klingons and code documentation (Score:3, Funny)