Slashdot Mirror
Successful Strategies for Commenting Your Code
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."
When I was learning Java in college, the instructor would give your failing grade if you don't have comments and the HTML output of the javadoc utility. The C++ instructors, on the other hand, only wanted your name, class and date in the comments. You would think that all programmers would comment their code.
I know the value of comments, so I always try to use them except in the smallest of personal utility programs. But I don't comment as I'm writing code. Instead, I write significant chunks of code, then go back and comment each piece of the chunk. In doing so, I have to think, "Okay, what is this code supposed to do?" and in the process, since I hadn't just finished writing the code, I tend to catch more typos and bugs. Seriously, I've saved myself a lot of time debugging by commenting this way.
I don't know why people (in general) don't like to comment code. I comment mostly for me, so a year or two down the line I'll know why I did something (I've found over the years of writing code, I may think I'll remember, but that often does not end up the case). In the end this selfish purpose ends up helping when other people need to maintain my code (other people fucking around with my code? Never).
"Who are in control, they are not in control of anything - they don't even control themselves!" - Glen Beck
I agree (I think) with you.
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
Listen to my latest album here
Good comments should explain these areas:
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?!"
Vivin Suresh Paliath
http://vivin.net
I like
Anyway, this is the strategy I've come up with after having to go over my old code.
Computers are useless. They can only give you answers.
-- Pablo Picasso
Two words: Literate Programming
(S(SKK)(SKK))(S(SKK)(SKK))
Well, there's nothing wrong with entertaining comments, as long as that's not *all* you have. In my experience, useful comments interspersed with a bit of humour can make code analysis and maintenence at least a little less boring.
Three rules of thumb that work fairly well:
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.
Stop-Prism.org: Opt Out of Surveillance
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.
perl -e "eval pack(q{H*},join q{},qw{70 72696e74207061636b28717b482a7d2c717b343 637323635363534323533343430617d293b})"
Actually, I start my programming projects by writing all the comments first; in this way, I get the pseudo-code ideas down and write the associated code under each comment. It helps me track where I am in a class/function, what I'm trying to accomplish (what parts still need to be written), and it nicely leaves an understandable trail without having to back-fill the code with comments once the project is "done."
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.
Diplomacy is the art of saying, "Nice doggie!" until you can find a rock.
The best basic strategy for commenting code is to flip the script: code your comments. Start writing the program by writing, in English (or your other human language in which you design programs), what the program will do. I start the file with a comment stating what the program will do, with any input and/or output to expect. Then I start writing complete sentences, punctuated, of the steps of processing. Wnen the action is obvious (already described in a comment), I sometimes label code with just a noun clarifying what its operating on. When I've got the comments written, I add code to each section, telling the computer how to do what I said it would in the comment.
/^(.+)\s+(.+)\s+(.+)$/);
:). While this clarity is useful when collaborating with other people, it's useful to consider that you are different when time passes. So reading your own code later is easier. Even if it's Perl, and you're cramming lots of "elegance" into some data structures and regexps - the comments can be clear.
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
--
make install -not war
would this be a good time for someone to explain to me why CSS doesn't support // comments, only /* ?
This comment does not represent the views or opinions of the user.