• (cs) in reply to Former Demon
    Former Demon:
    - Every single line of code needs a comment. - Every single closing brace } needs a comment.
    Sounds like a fine incentive to write a macro or add-in to search for uncommented lines, and if you want to get fancy, have it insert some generic comment such as:

    } // Close code block

  • (cs) in reply to snoofle
    snoofle:
    x = 5;
/**********************************************************
 * This is a comment on the practice of commenting code   *
 * that is used by many people */x/* Seriously, how can   *
 * you not trust what */=/* someone writes when they take *
 * the time to write not 1, not 2 nor even */3/* lines of *
 * explanatory text to show you */;/*what they had meant! *
 **********************************************************/
System.out.println("x="+x);

    I got 3 and I have no idea why... ;)

  • iMalc (unregistered)

    Paid by the line... (code or otherwise)

  • Demanding Hypocrite (unregistered)

    I think comments are unnecessary for most of the code. I demand everybody code for my desires. I think that anyone who needs comments is too stupid to write code. Finally my inability to use grep to remove comments from my own view has nothing to do with my own stupidity at all.

  • YourMoFoFriend (unregistered) in reply to KattMan
    snoofle:
    I got 3 and I have no idea why... ;)
    Read the comments, it's all clearly explained right there ;)
  • Bob N Freely (unregistered) in reply to JM
    JM:
    [dark voice] You underestimate the power of sequence.

    x = x + 1; y = x * 10;

    is easier than

    y = o.f(x)

    where o is in another file:

    class o { public f ( int i ) { int result = i; result = (i + 1) * 10; return result; } }

    Functions, loops and indentation have their place.

    I'm not sure how your example demonstrates anything. First off, your function f doesn't achieve the same results as the original code, since it doesn't modify the value of x. Secondly, the original code could be easily written in one line:

    y = ++x * 10;

    No need for refactoring. I think you misunderstood the argument. When you have complex pieces of code that include lots of loops and conditions, it might be a good idea to move some of that functionality to a subroutine to improve readability. Nobody thinks refactoring simple code is a good idea.

  • Jay (unregistered)

    I love it!

  • (cs)

    One of the (IMHO, few) places where comments are truly necessary is where the correct code "looks wrong." This may be because you're accounting for a fault in different system (if it's yours, you should have a comment in that system, but then you would have fixed it, right?) or something similar. The idea being to let future programmers (including yourself) know that it's right, and not just a mistake. It also helps if you make that comment clear enough that maintainers can tell when that condition no longer holds and can "fix" it properly.

    Most* other comments can be covered by good variable / module / function names and clear code. Any other code comments should describe why you're doing something. I can see what you're doing.

    *With the exception of brief module, function and variable descriptions as required by your coding standards and good sense.

  • James (unregistered) in reply to snoofle
    snoofle:
    x = 5;
/**********************************************************
 * This is a comment on the practice of commenting code   *
 * that is used by many people */x/* Seriously, how can   *
 * you not trust what */=/* someone writes when they take *
 * the time to write not 1, not 2 nor even */3/* lines of *
 * explanatory text to show you */;/*what they had meant! *
 **********************************************************/
System.out.println("x="+x);

    Evil! Love it!

  • James (unregistered) in reply to Bob N Freely
    Bob N Freely:
    y = ++x * 10;

    Yuck. Side effects. YUCK. Just go with:

    x += 1; y = x * 10;

  • Luke (unregistered)

    are you sure there was no coment for the method?

  • sammy (unregistered)

    I took a data structures class in college, and I swear that fully half (if not more) of the class was learning how to comment code rigorously, where by "rigorously" I really mean "like an obsessive jerk." Our "correct" comments looked pretty much like this in terms of verbosity.

  • JohnB (unregistered) in reply to AnonymousTart
    AnonymousTart:
    <snip>

    //start session //connect to db //select list of all users //output start of table //for each user // output row //end //close table //close connections

    The comments aren't designed to help you, the reader, but more me, the writer. They probably shouldn't be left around, think of it as mental scaffolding.

    "Mental scaffolding" - very nice turn of phrase and, yes, I do it, too.
  • iToad (unregistered)

    Is this some sort of attempt to implement Literate Programming [url]http://en.wikipedia.org/wiki/Literate_programming[\url] in Visual Basic? If so, the person who wrote this is going to need a programming environment a lot more sophisticated than Visual Studio.

  • iToad (unregistered)

    And I'm going to need an environment a lot more sophisticated than this BBCode editor. Like one with a preview function...

  • YourMoFoFriend (unregistered) in reply to JohnB
    JohnB:
    AnonymousTart:
    <snip>

    //start session //connect to db //select list of all users //output start of table //for each user // output row //end //close table //close connections

    The comments aren't designed to help you, the reader, but more me, the writer. They probably shouldn't be left around, think of it as mental scaffolding.

    "Mental scaffolding" - very nice turn of phrase and, yes, I do it, too.
    I think most developers do this, it's just a reminder of things to do..., a crude algorithm..., a pseudocode of sorts..., it's just a good idea really even if you forget to take those "step reminders" out when you're done. I'd much rather see these kind of comments than the ones in the article :)
  • (cs) in reply to iToad
    iToad:
    And I'm going to need an environment a lot more sophisticated than this BBCode editor. Like one with a preview function...
    Gee, I wonder what would happen if you were to, like, um, click the "Preview" button before you submit...
  • Stefan W. (unregistered)

    } // end case

    Mostly introduced by people, telling you, a 4 space indentation is enough (3, 2).

    Morons, everywhere.

  • Beaver (unregistered) in reply to Welbog

    A rather big method with lots of conditions and loops that might be hard to follow... Spaghetti!

  • Beaver (unregistered) in reply to AT

    Amen to that! Nothing like getting the code all pecker-tracked up with messy comments. Like throwing dirt in an engine.

    Fix it and test it. Use version control software for diffs.

  • Beaver (unregistered) in reply to AT

    Amen to that! Nothing like getting the code all pecker-tracked up with messy comments. Like throwing dirt in an engine.

    Fix it and test it. Use version control software for diffs.

  • Beaver (unregistered) in reply to TheRubyWarlock

    And comments get stale as the code slowly drifts. So you have to figure out what the comment means, and what the code is trying to do.

  • Beaver (unregistered) in reply to TheRubyWarlock

    And comments get stale as the code slowly drifts. So you have to figure out what the comment means, and what the code is trying to do.

  • Xaroth (unregistered)

    Clear code tells you what a block of code does. Clear comments tell you what a block of code is intended to do.

    One of these two informational needs is more important than the other to a maintenance coder. In my experience, it's been the latter that I've always wished for.

  • JohnFx (unregistered) in reply to DeltaGeek
    DeltaGeek:
    rd:
    What does "End Sub" do?

    CAPTCHA: Ha, ha! I'm a robot and I fooled this stupid test!

    VB is one of those silly languages that uses different terms for methods that return a value (Function) and methods that don't return anything (Sub(routine)).

    Unlike those unsilly languages that use descriptive techniques like putting "void" in front of the method name, right? If you use a language that reads more like English, perhaps you'd need less comments.

  • Bejesus (unregistered) in reply to Xaroth
    Xaroth:
    Clear code tells you what a block of code does. Clear comments tell you what a block of code is intended to do.

    One of these two informational needs is more important than the other to a maintenance coder. In my experience, it's been the latter that I've always wished for.

    Me I prefer to just read the name of the method and the name of the class that it's in and that should be all I need to know about the intent.

    If you find yourself needing to comment most of your code so that someone else can understand the intent behind it then you're writing shit code.

  • Xaroth (unregistered) in reply to Bejesus
    Bejesus:
    Xaroth:
    Clear code tells you what a block of code does. Clear comments tell you what a block of code is intended to do.

    One of these two informational needs is more important than the other to a maintenance coder. In my experience, it's been the latter that I've always wished for.

    Me I prefer to just read the name of the method and the name of the class that it's in and that should be all I need to know about the intent.

    If you find yourself needing to comment most of your code so that someone else can understand the intent behind it then you're writing shit code.

    Ah yes, the classic call of the person who never has to do maintenance on someone else's code, nor ever write code that others will have to maintain. (The last possible category being assholes who don't think about how their work affects others, but I'm sure you don't fall into that category.)

    I'll be sure to think of you and your extremely helpful advice the next time I encounter a function named "Q_rsqrt" in the "util" class, and wonder what the hell "i = 0x5f3758df - ( i >> 1 );" is doing in the code, why it's there, and what it was supposed to do.

    Strangely, a comment explaining the intent of the function, and a second comment explaining the intent of the magic number would save literally days in attempting to diagnose and correct the problem in a way that better naming of the function and variables won't.

    Amazingly, some of us have to fix the bugs of so-called "non-shit" programmers after they've already made the mess and left, so given the choice of having clear comments and no comments, I'll always take the former.

    (PS: Yes, this is a particularly famous example, tweaked to intentionally insert an easily-made bug, but it illustrates my point well.)

  • Andy Goth (unregistered) in reply to iToad
    iToad:
    Is this some sort of attempt to implement Literate Programming?

    In one module at work I have to write comments sufficiently verbose that someone can read them (and not the code) and still understand, at a high level, what the code does and how it works. This is because export requirements prevent us from giving this one particular customer the source code (usually we do give out our sources), so instead we deliver documentation from Doxygen, which we configure to emit all the comments. The result is basically literate programming. It looks really nice, actually, so long as the programmer is responsible enough to keep the code and the comments in sync. But it all goes to hell in a moment if the comments are unmaintained.

    This module contains several places where there's just a single line of code that does something very profound and difficult to grasp. These individual lines are preceded by paragraphs of comments which explain the ramifications and design considerations.

    For interesting and informative comments, have a look at the SQLite source code some time.

  • Andy Goth (unregistered) in reply to Xaroth
    Xaroth:
    Ah yes, the classic call of the person who never has to do maintenance on someone else's code, nor ever write code that others will have to maintain. (The last possible category being assholes who don't think about how their work affects others, but I'm sure you don't fall into that category.)

    My goal when documenting my code is to get the next programmer up to speed as quickly as possible. I imagine all the easy mistakes that can be made from ignorance, and the comments I write are specifically designed to prevent those mistakes. I think of all the things that weren't instantly clear to me, or that I suspect less experienced programmers can outright misunderstand, and I give them special attention. Basically I write the documentation I wish I had before I started working on the module.

    This also translates to the way I write my code. Whenever possible, I write it to maximize maintainability. And when forced to write tricky code, I do my best to make up for it in comments and external documentation.

  • iToad (unregistered) in reply to FredSaw
    FredSaw:
    iToad:
    And I'm going to need an environment a lot more sophisticated than this BBCode editor. Like one with a preview function...
    Gee, I wonder what would happen if you were to, like, um, click the "Preview" button before you submit...

    mmmm... aaaaah... duhhhh... The one next to the Submit button ??

  • Mr MIT (Mumbai Institute of Telephonists) (unregistered)

    the biggest wtf i see here is...

    "Output system error message to user on form under form title and send details to database"

    this means, every time a user enters an invalid SSN (assuming there is some sort of business logic in the set property) into the text box, an error will be logged to the database. How could an error log like that possibly be useful?

  • Adam (unregistered) in reply to Anon
    Anon:
    Seriously though, this gal is probably the only one on her team who doesn't use On Error Goto... for her error handling. She's just trying to stop the other eager veabers from putting her code inside an On Error Resume Next in case there are any unhandled errors.

    Error handling in VB - The real WTF!

    Did you notice the structured exception handling? This is VB.NET, not VB. There is no On Error Resume... in VB.NET.

  • (cs) in reply to Former Demon
    Former Demon:
    You have no idea. I've been all the way down to the end of the road and though the gates into the fire pit. I had code reviews with Satan himself.

    Imagine it until it hurts, then stop:

    • Every single line of code needs a comment.
    • Every single closing brace } needs a comment.

    If you screw up just one space, the boss starts yelling at you for a minute or more:

    } // This is okay

    } // This will get you yelled at

    I'm not making this up.

    I'm usually pretty easy-going, but even at that point I would be telling boss to f*ck off if he yelled at me for that.
  • Spike (unregistered) in reply to Bejesus
    Bejesus:
    Even the //bug 897123 fixed here ones are utterly pointless, that's what version control systems are for.
    A comment reading "bug 897123 fixed here" is of course utterly pointless. But how about "do not destroy object foo here because there may still be elements referencing it"? This way, your successors neither have to sift through the entire history of that particular source file nor will they accidentally reintroduce that particular bug.
  • (cs) in reply to Xaroth
    Xaroth:
    Ah yes, the classic call of the person who never has to do maintenance on someone else's code, nor ever write code that others will have to maintain. (The last possible category being assholes who don't think about how their work affects others, but I'm sure you don't fall into that category.)

    I'll be sure to think of you and your extremely helpful advice the next time I encounter a function named "Q_rsqrt" in the "util" class, and wonder what the hell "i = 0x5f3758df - ( i >> 1 );" is doing in the code, why it's there, and what it was supposed to do.

    Strangely, a comment explaining the intent of the function, and a second comment explaining the intent of the magic number would save literally days in attempting to diagnose and correct the problem in a way that better naming of the function and variables won't.

    Quite unstrangely, you are wrong. Better naming of the function and the constant that magic number should be in WOULD convey most of the information you need. And it's less likely to be out of sync with what the code does.

    Besides, the kind of comment you get out of compulsive commenters would be

    /* 
 * Perform Q_rsqrt on i
 * Parameter: int i
 * Return value: int
 */
int Q_rsqrt(int i) {
    i  = 0x5f3758df - ( i >> 1 ); // Subtract i right-shifted by 1 from 0x5f3758df 
}

    unless it's

    /* 
 * Perform W_lsqrt on x
 * Parameter: long x
 * Return value: *char
 */
int Q_rsqrt(int i) {
    i  = 0x5f3758df - ( i >> 1 ); // Subtract x right-shifted by 2 from 0x7f3758df 
}

    In my experience, quality of comments is inversely related to their amount.

  • (cs) in reply to Pingmaster
    Pingmaster:
    plus, most IDE's these days allow you to collapse the comment blocks if they're in the way, some even have a feature to automatically collapse all comment blocks, so overly verbose comments don't really get in the way of the code.
    Oh yes, that's SO going to help with keeping the comments up-to-date and relevant...
  • (cs) in reply to JM
    JM:
    Sven:
    Extracting part of it into a well-named function can make a world of difference.

    It won't remove the need for comments completely, to be sure, but it might reduce it.

    [dark voice] You underestimate the power of sequence.

    x = x + 1; y = x * 10;

    is easier than

    y = o.f(x)

    A well-named function if ever I saw one. Not!

    Fabian

  • Cloak (unregistered) in reply to Anon
    Anon:
    Error handling in VB - The real WTF!

    Why??? What's so WTFy to write On Error Goto instead of try..catch? Is the meaning of the words better chosen or is it because you need to write more letters in VB?

  • Cloak (unregistered) in reply to DeltaGeek
    DeltaGeek:
    VB is one of those silly languages that uses different terms for methods that return a value (Function) and methods that don't return anything (Sub(routine)).

    C++ and Java are some of these silly languages that need a key word to describe the one and only possible start of a function/procedure.

  • Cloak (unregistered) in reply to Aaron
    Aaron:
    but I can think of far worse crimes.... coding in VB for example!

    For me the bigger crime is to give written evidence of stupid one is...

  • Cloak (unregistered) in reply to Aaron
    Aaron:
    but I can think of far worse crimes.... coding in VB for example!

    For me the bigger crime is to give written evidence of stupid one is...

  • Cloak (unregistered) in reply to vt_mruhlin
    vt_mruhlin:
    Reminds me of college classes where we had to describe the inputs and outputs of ALL functions. I was always a smartass...

    ////////////////////////// // Rectangle::GetWidth() // // input: none. // output: The exact value of pi.

    int Rectangle::GetWidth(){ return m_iWidth; }

    "// output: The exact value of pi." A good example of mis-leading comments

  • Cloak (unregistered) in reply to Stefan W.
    Stefan W.:
    } // end case

    Mostly introduced by people, telling you, a 4 space indentation is enough (3, 2).

    Morons, everywhere.

    What's wrong with 4 spaces? I use 4 instead of 2 as many C-guys do. But the code is more difficult to read for me with only 2 spaces.

  • Synonymous Awkward (unregistered) in reply to Cloak
    brazzy:
    Xaroth:
    Strangely, a comment explaining the intent of the function, and a second comment explaining the intent of the magic number would save literally *days* in attempting to diagnose and correct the problem in a way that better naming of the function and variables won't.
    Quite unstrangely, you are wrong. Better naming of the function and the constant that magic number should be in WOULD convey most of the information you need. And it's less likely to be out of sync with what the code does.

    Ununstrangely, there is no name for that particular magic number. The function is the not-as-well-known-as-it-should-be technique for computing fast reciprocal square roots, and it basically depends entirely on using IEEE floats. The best way to explain exactly what it's doing to a maintainer is to tell them. In a comment.

    Cloak:
    C++ and Java are some of these silly languages that need a key word to describe the one and only possible start of a function/procedure.
    What language do you use where you can have more than one entry point to a function/procedure? ;-o
  • Cloak (unregistered) in reply to Synonymous Awkward
    Synonymous Awkward:
    brazzy:
    Xaroth:
    Strangely, a comment explaining the intent of the function, and a second comment explaining the intent of the magic number would save literally *days* in attempting to diagnose and correct the problem in a way that better naming of the function and variables won't.
    Quite unstrangely, you are wrong. Better naming of the function and the constant that magic number should be in WOULD convey most of the information you need. And it's less likely to be out of sync with what the code does.

    Ununstrangely, there is no name for that particular magic number. The function is the not-as-well-known-as-it-should-be technique for computing fast reciprocal square roots, and it basically depends entirely on using IEEE floats. The best way to explain exactly what it's doing to a maintainer is to tell them. In a comment.

    Cloak:
    C++ and Java are some of these silly languages that need a key word to describe the one and only possible start of a function/procedure.
    What language do you use where you can have more than one entry point to a function/procedure? ;-o

    public/private function XXX public/private procedure XXX

    QED

  • (cs) in reply to Cloak
    Cloak:
    Synonymous Awkward:
    Cloak:
    C++ and Java are some of these silly languages that need a key word to describe the one and only possible start of a function/procedure.
    What language do you use where you can have more than one entry point to a function/procedure? ;-o

    public/private function XXX public/private procedure XXX

    QED

    Neither "function" nor "procedure" is a keyword in either C++ or Java.

  • (cs) in reply to Synonymous Awkward
    Synonymous Awkward:
    brazzy:
    Xaroth:
    Strangely, a comment explaining the intent of the function, and a second comment explaining the intent of the magic number would save literally *days* in attempting to diagnose and correct the problem in a way that better naming of the function and variables won't.
    Quite unstrangely, you are wrong. Better naming of the function and the constant that magic number should be in WOULD convey most of the information you need. And it's less likely to be out of sync with what the code does.

    Ununstrangely, there is no name for that particular magic number. The function is the not-as-well-known-as-it-should-be technique for computing fast reciprocal square roots, and it basically depends entirely on using IEEE floats. The best way to explain exactly what it's doing to a maintainer is to tell them. In a comment.

    The function name can and should tell the purpose of the function quite adequately. No comment needed. The exact method is indeed something that needs commenting. I hope you'll agree that it's an extreme and exceptional case though.

  • Demanding Hypocrite (unregistered) in reply to Beaver
    Beaver:
    Amen to that! Nothing like getting the code all pecker-tracked up with messy comments. Like throwing dirt in an engine.

    Fix it and test it. Use version control software for diffs.

    Absolutely! That way when a change elsewhere causes a break, you have no comments to understand the nuances of the original code and why it expected any particular set of conditions. Way to plan ahead and consider others at the same time!

  • (cs) in reply to Demanding Hypocrite

    I hold pretty firmly to the belief that comments in modern programming languages should only be used to explain the "why" and not the "what" or the "how."

    Addendum (2007-10-02 11:20): I see comments like this in the system I've inherited:

    'Set file lock SetFileLock()

  • Bejesus (unregistered) in reply to Xaroth
    Xaroth:
    Ah yes, the classic call of the person who never has to do maintenance on someone else's code, nor ever write code that others will have to maintain. (The last possible category being assholes who don't think about how their work affects others, but I'm sure you don't fall into that category.)
    I both maintain other people's code and write code others will have to maintain all the time.

    Comments are only useful or helpful to explain the obscure quirks. Otherwise they are misleading junk that will never get updated.

    Why would you need a comment to explain the intent of a method named "calculateMonthlyInterest()" or "suspend()"?

    Some of the code I maintain (written by a team of fresh out of college grads in Bangalore 5 years ago) is WTF heaven. 7,000 line methods, copy/paste errors the lot. The comments don't help and are often wrong.

    Xaroth:
    I'll be sure to think of you and your extremely helpful advice the next time I encounter a function named "Q_rsqrt" in the "util" class, and wonder what the hell "i = 0x5f3758df - ( i >> 1 );" is doing in the code, why it's there, and what it was supposed to do.

    Strangely, a comment explaining the intent of the function, and a second comment explaining the intent of the magic number would save literally days in attempting to diagnose and correct the problem in a way that better naming of the function and variables won't.

    "i = 0x5f3758df - ( i >> 1 );" is an obscure quirk that deserves a comment. I posted earlier in the thread, that's the only case in which you should need them - to explain stuff that isn't easily made self documenting in the code.

    The method name is shit. Instead of a comment saying what the method does, it would be better for the name to actually mean something.

    Xaroth:
    Amazingly, some of us have to fix the bugs of so-called "non-shit" programmers after they've already made the mess and left, so given the choice of having clear comments and no comments, I'll always take the former.

    (PS: Yes, this is a particularly famous example, tweaked to intentionally insert an easily-made bug, but it illustrates my point well.)

    You don't get a choice of clear comments or no comments. You get a choice of randomly scattered inconsistent and out of date down right misleading comments or hardly any comments except where they're absolutely needed to explain *magic*. The latter is the only useful option.

Leave a comment on “The Road to Hell”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article