Successful Strategies for Commenting Your Code 500
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."
What's So Hard About Comments... (Score:3, Interesting)
My commenting habits (Score:3, Interesting)
Why I comment code... (Score:5, Interesting)
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 through the entire code base, and format the comments to the "company standard". No shit.
Bob
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?!"
My take (Score:3, Interesting)
Anyway, this is the strategy I've come up with after having to go over my old code.
Literate Programming (Score:3, Interesting)
Two words: Literate Programming [wikipedia.org]
Re:My favorite code comment not written by me (Score:5, Interesting)
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.
Re:Don't do it! (Score:2, Interesting)
Indispensibility is what keeps your job when the company for which you have produced code is purchased explicitly for the ownership of said code and someone must know how to use it.
I can speak from experience, having witnessed such a purchase firsthand. The entity which did the purchasing stated outright that in order to use the code they bought the company for, they would need to keep the select few coders that knew it intimately. The source and build processes had little to no commenting or documentation, so without the programmers, the source for the products was useless. Thus 2 coders that were heavily involved in those projects and 2 other employees in other departments were given the power to negotiate a salary and keep their jobs while the rest of the company got shitcanned. Had the code been well documented and the purchaser not needed its authors to interpret it, those people would have at best been given below average compensatory salary offerings at best, or more likely notices of immediate employment termination.
In a perfect world, we'd all have well documented code. But unfortunately in the real capitalist faux-utopia that we live in, if you aren't necessary for the operation of your own code, you become worthless in comparison to it.
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.
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 that aside, knowing how to write good comments, and actually taking the time to write the comments are 2 different matters entirely. In many cases by the time programmer gets around to coding they are frequently tired of documenting what they're doing. Because they're had to write Analysis Documents, Design Documents, and Test Plans. They code doesn't need documentation because "they've already documented the hell out of the project". And guess what, that code may be thrown away in 5 years or so anyway because there's a better way of doing things. Anybody maintaing EJB 1.0 or JSP 1.0 apps these days? (I know there are a few left, but those are the exception.)
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
CSS (Score:2, Interesting)
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 comment made sense where it was. And don't forget the old code that had comments that no longer matched what the code did!!!
All in all, I prefer the "code smells" approach to comments -- when you see a comment, think carefully about whether it's a good thing in itself, or whether it's actually being used to hide bad code. For an example of a question I might ask, with your comment "# Store fields in their columns", might it possibly be better to have a function named StoreFieldsInTheirColumns()?
-Billy