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."
These comments you speak of, they seem foreign and strange to me.
I was doing some maintenance on someone else's code and came across this nasty set of like 8 nested if/elses. It was a bloody horrible hack. But the best part of all was the comment right at the top: /* Oh, fuck */
-- (Score:i , Imaginary)
/* no */
/*This loop starts at x is equal to 1 and continues while x is less then 5. x is incremented by 1 each time.*/ for( int x=1; x5; x++ ) { printf("Hello World\n");/*Prints "Hello World"*/ }
My best strategy is intelligent variable names and clean simple code. -- http://www.dreamsyssoft.com
I viewed the source on the site and nothing was commented :)
Finance tutorials and more! Understandfinance
Comments are more important than Code?
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.
Don't comment at all, and just run it thru The Commentator!
http://www.cenqua.com/commentator/
Don't blame me, I voted for Kodos
But when reading the article I was glad that the very first item was SELF DESCRIBING CODE. The most important part of code documentation is the code iteself IMHO.
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()...
Write the comments first, then add the code. That way you'll get a better grasp on the problem you're solving. If your comments don't explain the problem or someone else can't solve the problem using your comments then you'll probably need to rethink your approach.
And for crying out loud update the comments when you change code!
*grumbles about 10 year old code and 15 year old comments*
The next generation of professional coders will most likely be good commenters as well. I know from experience in my computer science classes, professors will mark programming assignments down significantly if comments are not included, or if they are hard to read. Most of the time they want all functions to be commented to explain what their parameters mean, how the function works, and the format of the output.
I got nothin'
No, that first one should be something like:
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...
The AACS key is NOT 0xF606EEFD628B1CA427BEA93A9CA9773F
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.
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.
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
1. Never spelchezk. /* magic occurs */
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.
-- Tigger warning: This post may contain tiggers! --
# 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
-"...bad old ideas look confusingly fresh when they are packaged as technology" - Jaron Lanier (Digital Maoism on Edge.o
It's been said before, but I find the best advice I've ever gotten on commenting code is very simple -
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.
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
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.
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
Ask someone else to look at your code. Every time they pause while scrolling, touch their chin, squint their eyes, furrow their brows, etc., it means you need a comment.
[o]_O
Successful Strategies for Crashing Your Website
This post expresses my opinion, not that of my employer. And yes, IAAL.
This works quite well, but there are some consequences for this action:
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'
The List of Grievances with Slashdot.
Two words: Literate Programming
(S(SKK)(SKK))(S(SKK)(SKK))
This kind of reviews are really destructive for my goal of winning the obfuscated code contest (http://www.ioccc.org/ can not read any further.
My wife's sketchblog Blob[p]: Gastrono-me
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
There are two problems with this.
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 clearly named that your grandmother could tell you what it's used for or be commented. Etc.
It takes seconds or minutes to write comments. One comment can save you hours of time and loads of frustration. Common sense says to write the comments, even if you don't think you'll need them. You only need to be wrong once or twice to come out ahead.
"The legitimate powers of government extend only to such acts as are injurious to others." Thomas Jefferson.
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})"
You still need to know how to write good comments but I find using doxygen is a great tool for generating useful documentation directly from comments in your code. If you haven't heard of it give it a shot.
http://www.stack.nl/~dimitri/doxygen/ Doxygen homepage.
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
OK, it s not always possible and/or desirable. If it is not broken don't fix it. When I see comment in code because the developer don't understand what happening in 8 level deep statement or in the little function of 10000 lines of code, please fix the code.
there is basic rules to follow; not all exposed here it would be tooooo easy and me way too lazy :) :
Comments are there to
NB: I know javadoc, junit and metrics is for java but...
"Use cases are fairy tales..." I. S. 2005
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.
I recently took a contract somewhere as an 'engineer' where I was probably the only one who had an engineering degree. Also the work I was doing was far from engineering (web programing). Also I've been on interviews where the client sets me up to talk with their "engineer" who probably doesn't even have a college degree. The problem I've run into is that many times the ones doing the hiring have no idea what they are talking about. To them the engineer is the guy who can use the terminal, or can write HTML by hand.
Another problem ( I think I'm on a rant here ) is that some people say they want an engineer when what they want is a designer, they want someone to make their site look pretty, and they really don't care about functionality. They just figure "Its too technical for me so I must need an engineer."
(The situation isn't helped by people who use flash and call them selves an engineer)