Slashdot Mirror
How to Write Comments
Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See "
Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.
Code should read easy Like many Slashdot comments See? It's not so hard.
ACs are modded -6. I don't read you, I don't mod you, I don't see you. Don't like it? Don't be a coward.
<!-- why don't they ever RTFA? -->
<b>Nothing for you to see here. Please move along.</b>
liqbase
Simple, and I've posted this link a few times before, but you really need to use cenqua. Takes all the pain out of comments, and still allows personality quirks to show thru.
The Commentator
Just be careful on your settings and you should be fine.
Don't blame me, I voted for Kodos
Rob Pike, a former powergeek at ATT&T labs, and a present powergeek at Google, has the following to say about code commenting. In general, I agree with him.
Just like good documents are self coding...
If I could, I'd destroy you all.
During college I always lived by:
"It was hard to write; it should be hard to read"
'course the profs didn't appreciate that much...
Possibly the best advice I ever read/heard (I can't remember the origin), is to assume that the guy reading your code is perfectly familiar with the language. (Sadly this is usually inaccurate, but moving on.) So he can see what, mechanically, your code is doing. The idea of a comment is to explain how and why you are doing something. What is usually clear from the function name and accompanying documentation (be it doxygen/javadoc style or MSDN style or something else). I.e. if you have some jacked up mega-compound for-loop, a good comment explains why that loop is the way it is, and how it's achieving its goal (and possibly what precisely it's doing). A bad comment would be "this loop increments i, j, k, theta, and cheez_it until the cheez_it is failing to exceed the sum of i, j and the product of i, j, and k". That kind of information is right there in the code.
In short, comments convey concepts and explanations, not mechanical descriptions.
He's used two stupid examples of commenting, examples that are popular jokes, rarely appearing in real life and usually the result of sarcastic nudge-nudging from experienced programmers, and pretended that's what we're talking about when we talk about commenting. When he finally admits they may have a use, the description is so vague it's hard to see what he means - which, if he comments the same way, is probably as true of his code as it is his prose.
It doesn't take much, or add any clutter to code, to put a brief, one or two line, comment before each paragraph of code, that describes the intended functionality of the code block. It makes a massive difference when you revisit your code three years, or even three months, later, or worse have a collegue look at it.
Nor is it a massive imposition to have more obscure decisions you've made be explained in a comment block before the code itself.
Code is not self-documenting. It becomes intensely verbose when you try to make it self-documenting, and it's rare that anyone, no matter how well skilled, can produce something that transmits the intended functionality of the written code in the implemented functionality. This is especially true if you're using an optimal algorithm. Reasonable, non-excessive, use of comments, describing functionality rather than function, are extremely important.
You are not alone. This is not normal. None of this is normal.
What about doing this?
/* makes it public */ public /* boolean value */ bool /* function name */ CheckSmsValue( /* function parameters */Account smsAccount)
/* start function */{
/* Comment */
// Check tarriff is null
/* if statement */ /* variable */ Account.Tarrif /* equals */ == /* Null */ null)
/* return */ return;
/* dot, dot, dot */ ...
/* end function */}
if (
The code is the 'How'. What the reader needs to know is 'Why' you are taking these steps. What larger goal are you accomplishing? What is the purpose of this code? What is its justification for existance?
Fill in this blank: "If were weren't running this code right here right now, we wouldn't be able to do _____. We could have done it this other way, but we chose this method because of X, Y, and Z.
In a real world example, code is like "Turn left, Go to High Street, turn right, continue on to 1122 High St, pull into the driveway, and park the vehicle." Those are the steps taken, but the goal you are acommplishing is "We want to return the library books, so we are going to drive the books to the library using the car."
OK, so why are we taking the books to the library? Ultimately all comments will filter up to the goals of the application. They are all nested subgoals of the design specs.
Computers are useless. They can only give you answers.
-- Pablo Picasso
Sorry, but you happened to hit on one of my pet-peeves with non-self-descriptive code. I do agree with your suggestions, mind you, but I see it all the time: functions describing how they work, not what they do. Sorry to pick on you, but in this case why not take:
public bool CheckSmsValue(Account smsAccount)
{
And instead say:
public bool isSmsValueAccurate(Account smsAccount)
{
That way, anyone who glances at the call will know what the function does. In fact, the first one could be checking for existance, non-existance, accuracy, threshold, who knows? Heck, its exactly the kind of function that I could see being called in many different places by people expecting it to be checking different things. Or coder1 adds it in expecting it to check for "positive" as well as whatever else, months later coder2 realizes that it doesn't and adds the "extra check" into it - its a check function, after all, right? And then coder3's code in some far-away place suddenly starts failing because he didn't want that check in the function.
A good name should be an implict contract. The function above should, by that definition, return "true" if it did at least "check" the SmsValue, and "false" if it didn't bother to... not quite what the original intent was. Probably.
Phew. Sorry for the long-windedness.
You're special forces then? That's great! I just love your olympics!
The 1st rule of software engineering is: you do not put hacks in your projects :)
The 2nd rule of software engineering is: you DO NOT put hacks your projects
The 3rd rule of software engineering is: document you hacks
The 4th rule of software engineering is: one hack at a time
The 5th rule of software engineering is: if this is your first project, you'd have to do lots of hacks.
> I once read that a good comment will appear on every conditional branch or loop
But be sure to put them outside the loop, so people won't have to read them over and over.
Sheesh, evil *and* a jerk. -- Jade
If you are programming anything non-trivial, you are going to have sections of code that are obscure, and when you have to go back and fix a bug, or add functionality, you won't have any idea what the hell you were doing.
For example, I've written code that had to run on displays with 256 color palettes in windows. It involved saving the current palette when the window gained focus, and then restoring it when the window lost focus. But I couldn't even tell you how I did that now. If I had to go back and look at that code today, I'd have no idea what I was thinking. I do recall that is wasn't actually very many lines of code.
Back before UML was a common thing, I used to 'write' my code in comments and stubs, as a design. After I could read through the code as a narrative of what my app/service/dll did, I would actually fill in the stubs to make it work. This ended up saving me a lot of time in the long run, as I didn't really have much refactoring work to do while coding.
Since when did operating systems become a religion?
That's some of the worst advice I have seen wrt. code commenting. Comments should never describe what the code does. If it is not obvious from the code, it should be refactored.
The strategy of verbose and essentially redundant comments are bound to end up in outdated and/or useless comments. If such a practice is employed in industry, forcing people to comment every loop, etc. as you describe, I'm certain there would be a lot of useless comments.
People will simply not do something, which they cannot see how they would later benefit from. Classic CSCW problem.