• Dirk (unregistered)

    I love VB. Who needs block comments anyway? (Frist?)

  • Nelle (unregistered)

    i mean, we programmers are a weird bunch, we rant when there are no comments, seems we don't like when they are ... whatever these are ... when is it "just right" ...

  • BestSnowman (unregistered)

    Nice WTF, VB... and those comments are pretty much their own WTF. :)

  • commenter (unregistered) in reply to Nelle

    While method header comments or .NET documentation comments are a different animal, in-body comments are just right when they are sparse enough that you only notice them when you need them, but detailed enough that they make the surprises apparent. In other words, don't tell us about language features(unless they are VERY obscure), standard library functions(unless they are obscure or there is a workaround\known problem that affects the code), or standard idioms like iteration. We should be able to get that information from the code itself or the code is bad.

    In my opinion, when commenting code directly, just tell us why you're formatting a zipcode as a float or dividing the social security number by 6, or that a bug was fixed here. There is no real need to duplicate the line of code in English, regardless of what college teaches you. Simple methods don't need block in-line comments.

  • The Barefoot Bum (unregistered)

    I'm shocked, SHOCKED! that this otherwise careful and thorough programmer failed to comment the "End Try" line.

  • rd (unregistered)

    What does "End Sub" do?

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

  • (cs)

    //above here is the subject, entered to detail reply

    //Bellow is comment body, where witty retorts are entered. Haha this is a sweet WTF.

    //bellow here is where you write you captcha if you didn't login

    //bellow here is where submit is pressed to submit comment

  • (cs) in reply to Vechni
    Vechni:
    //above here is the subject, entered to detail reply

    //Bellow is comment body, where witty retorts are entered. Haha this is a sweet WTF.

    //bellow here is where you write you captcha if you didn't login

    //bellow here is where submit is pressed to submit comment

    "Bellow here" is quite an interesting (pun-ny) choice of words for comments that "shout" about code.

  • PACE (unregistered) in reply to commenter
    commenter:
    In my opinion, when commenting code directly, just tell us why you're formatting a zipcode as a float or dividing the social security number by 6, or that a bug was fixed here. There is no real need to duplicate the line of code in English, regardless of what college teaches you. Simple methods don't need block in-line comments.
    I disagree. While simple methods like the one above would not need in-line comments, they're still helpful even if you are not doing something obscure, just toi describe WHAT you are doing - not HOW. So it is easier to find a specific position or work on someone else's code.

    benj

  • (cs) in reply to PACE
    PACE:
    commenter:
    In my opinion, when commenting code directly, just tell us why you're formatting a zipcode as a float or dividing the social security number by 6, or that a bug was fixed here. There is no real need to duplicate the line of code in English, regardless of what college teaches you. Simple methods don't need block in-line comments.
    I disagree. While simple methods like the one above would not need in-line comments, they're still helpful even if you are not doing something obscure, just toi describe WHAT you are doing - not HOW. So it is easier to find a specific position or work on someone else's code.

    benj

    I agree to some extent with that, but sometimes the how is important, too. If I've written a rather big method with lots of conditions and loops that might be hard to follow, I'll typically preface it with a comment describing the algorithm used (the how) along with a description of the purpose of the algorithm (the what), along with the usual inline comments explaining bug fixes and weird math.

  • Cpt (unregistered)

    No comments is not good, now I provide comments it is not good either.. you just can't win can you!! ;)

  • commenter (unregistered) in reply to PACE
    PACE:
    commenter:
    In my opinion, when commenting code directly, just tell us why you're formatting a zipcode as a float or dividing the social security number by 6, or that a bug was fixed here. There is no real need to duplicate the line of code in English, regardless of what college teaches you. Simple methods don't need block in-line comments.
    I disagree. While simple methods like the one above would not need in-line comments, they're still helpful even if you are not doing something obscure, just toi describe WHAT you are doing - not HOW. So it is easier to find a specific position or work on someone else's code.

    benj

    That, IMHO, is the duty of a header comment, which I excluded in my first paragraph. Something like:

    //FuncA //Description: Does X, Y, Z //Remarks: etc, etc void FuncA(X,Y,Z)

    With something as simple as that and short, to the point methods, you shouldn't need a comment at every line for clarities sake. I'm not going to say you should never comment, just that a comment should be as well thought out and utilitarian as every other line of code, not throw in excuses not to make sense IN code.

  • AT (unregistered) in reply to commenter
    commenter:
    In my opinion, when commenting code directly, just tell us...that a bug was fixed here.
    No, please don't tell us that a bug was fixed here! That's what version control software is for!
  • Tp (unregistered)

    Getting paid by lines of code is sooo 90's, now we are paying for lines of comments!

  • wtf (unregistered)

    maybe not by lines of code, but hourly. and it takes a while to type that crap out

  • Sven (unregistered) in reply to Welbog
    Welbog:
    If I've written a rather big method with lots of conditions and loops that might be hard to follow
    Then you need to refactor it. :)
  • (cs) in reply to Sven
    Sven:
    Welbog:
    If I've written a rather big method with lots of conditions and loops that might be hard to follow
    Then you need to refactor it. :)
    Except for the fact that a refactored complicated algorithm is still a complicated algorithm and would still need an adequate description of how it is accomplishing the task. Refactoring merely moves the location of such a description.
  • Sven (unregistered) in reply to Welbog
    Welbog:
    Sven:
    Welbog:
    If I've written a rather big method with lots of conditions and loops that might be hard to follow
    Then you need to refactor it. :)
    Except for the fact that a refactored complicated algorithm is still a complicated algorithm and would still need an adequate description of how it is accomplishing the task. Refactoring merely moves the location of such a description.
    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.

  • DeltaGeek (unregistered) in reply to rd
    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)).

  • (cs) in reply to PACE
    PACE:
    I disagree. While simple methods like the one above would not need in-line comments, they're still helpful even if you are not doing something obscure, just toi describe WHAT you are doing - not HOW. So it is easier to find a specific position or work on someone else's code.
    I disagree violently. Commenting the obvious does not help, it in fact decreases maintainability by cluttering up screen space with useless and possibly wrong (when the code is changed and the comments are not) information. Such comments make it HARDER to find a specific position or work on someone else's code!

    My personal rules of commenting:

    1. Use descriptive variable and method names instead.
    2. Where these are not sufficient, add comments about method contracts and the content of variables to their declarations.
    3. only very, very rarely should actual code need commenting if it's well-designed.
  • (cs)

    And by the way, what's with the subErrorReporting name? What's that sub prefix for?

  • (cs) in reply to rd
    rd:
    What does "End Sub" do?

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

    We are the robots. Robot I am. I am registered, so I have no tests. No Quack.

  • rokclimb (unregistered)

    You would hope that they would know what try, catch, and = are, but you would be surprised.

    I used to write comments on this level of difficulty for my old boss, just in case he had to maintain the code someday. And as it turned out, he did!

  • Aaron (unregistered)

    If given a choice between superfluous over-commenting and no commenting (or not enough) I'll take the over-commenting any day of the week. You can always delete unnecessary comment blocks if they're that annoying.

    Besides, isn't complaining about this like complaining about someone who compulsively uses their turn signals after checking their blind spots when changing lanes? I mean -- I agree that in this case the commenting was grossly unnecessary; but I can think of far worse crimes.... coding in VB for example!

  • Ian (unregistered) in reply to commenter
    commenter:
    ... or standard idioms like iteration. We should be able to get that information from the code itself or the code is bad.

    On occasion, I'll comment iterators if they're nested or I just think it'll be easier to read.

  • wiregoat (unregistered) in reply to T_PAAMAYIM_NEKUDOTAYIM

    Why comment when you can just put it all in the function name? If you don't have carpal tunnel then aren't doin' it right.

    public function functPoindexterIsMyCaption as boolean.

  • ChrisB (unregistered)

    I spotted this in some PHP code the other day:

    // start the session session_start();

    Now can anyone tell me how that comment added any value to the code?

  • James (unregistered)

    subErrorReporting means that some company is insisting upon using Hungarian notation for function names. Talk about going way over-the-top.

    I'm sorry, I don't care what any of you say, this is moronic. This is someone who is wasting their company's time. And, anyone who cannot read this code without the huge comment block is also a moron.

    This code is trivial and should require zero explanation to understand. If you do require explanation for this code, you should be in school and not getting paid.

  • (cs)

    While the act of commenting the code is commendable.. what's the old rule? Useless comments are worse than no comments at all?

  • dkf (unregistered) in reply to brazzy
    brazzy:
    My personal rules of commenting: 1) Use descriptive variable and method names instead. 2) Where these are not sufficient, add comments about method contracts and the content of variables to their declarations. 3) only very, very rarely should actual code need commenting if it's well-designed.
    Nice ideal, but it doesn't quite work like that in practice. While yes, the purpose of comments is to reveal such information as is not obvious from the code itself, the nature of that information is not always neatly captured by things like contracts. For example, a comment may also note that a particular strange way of writing things is due to an optimizer bug (yes, that's bitten me in the past and it sucks!) or some non-obvious thing about how a particular API (especially an external library API) is used. Of course, details of an API's obscurities might be obvious to someone truly deep in the code, but that's not something it's wise to count on.

    The rule with comments is always to use them to make the code easier to read. Whatever that means. It takes good taste and a proper sense of code-smell...

  • dkf (unregistered) in reply to dkf

    Bother: forgot to bbcode the italics... :-(

  • James (unregistered)

    When I hear "CMMI", this post is more or less exactly what comes to mind.

    Is that unfair?

  • Anon (unregistered)

    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!

  • Valdis (unregistered) 
    "Plus, I'd hope that any developer maintaining this would know what "try," "catch," and "=" are."

    You're new here, aren't you? :)

  • Bogglestone (unregistered) in reply to ChrisB
    ChrisB:
    I spotted this in some PHP code the other day:

    // start the session session_start();

    Now can anyone tell me how that comment added any value to the code?

    Yes.

  • Andy Goth (unregistered)

    This reminds me of college. I often helped other students with their programming, and I could always tell who had taken classes with which professor, since they invariably used the same idiotic block comments in front of every file, function, and other major structure. The block comments included worthless information such as the freakin' hostname of the computer used to write the code!

    Understand that this would be years after the student had passed the course in which they were (ahem) programmed to use this comment format. When asked about it, they would tell me that they just got into the habit after being required to do it for so many assignments.

    Imagine these poor souls when they get real jobs. Or, imagine the poor employers who hire them! How very sad.

  • (cs)

    Funny that this topic should come up now. Today I'm working on an update to existing code, and here's what I found when I opened the source. Looks like the previous coder had his output switch set to "verbose":

    public void LoadUserControls()
{
  PatientDetails patientDetails = this.FindControl("ctlPatientDetails") as PatientDetails;
  // At what point does this.Controller get set and from where?  Answer:
  // Default.aspx.cs invokes the Controller property set method defined above; it
  // does so from its DisplayPatientSummary() method which is invoked from its 
  // page_load routine.
  // This works because the page_load method of a page gets invoked before
  // the page_load method of any controls it contains.
  patientDetails.Controller = this.Controller;
  (snip)
}
  • Global Warmer (unregistered) in reply to Sven
    Sven:
    Welbog:
    Sven:
    Welbog:
    If I've written a rather big method with lots of conditions and loops that might be hard to follow
    Then you need to refactor it. :)
    Except for the fact that a refactored complicated algorithm is still a complicated algorithm and would still need an adequate description of how it is accomplishing the task. Refactoring merely moves the location of such a description.
    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.

    I couldn't agree more!!!!

  • AnonymousTart (unregistered) in reply to ChrisB
    ChrisB:
    I spotted this in some PHP code the other day:

    // start the session session_start();

    Now can anyone tell me how that comment added any value to the code?

    If I'm writing something in a tinky tonky toy language like PHP, I often won't start by writing a detailed design. I'll think for about 5 minutes, and then write the entire file, using comments for any bits that are boring, and/or can't expand without looking away from the file.

    eg:

    //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.

    On the other hand, maybe whichever colleague wrote the code has evaluated his peers and found that those sorts of comments are required..

  • (cs) in reply to Aaron
    Aaron:
    If given a choice between superfluous over-commenting and no commenting (or not enough) I'll take the over-commenting any day of the week. You can always delete unnecessary comment blocks if they're that annoying.

    Besides, isn't complaining about this like complaining about someone who compulsively uses their turn signals after checking their blind spots when changing lanes? I mean -- I agree that in this case the commenting was grossly unnecessary; but I can think of far worse crimes.... coding in VB for example!

    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.

  • sf (unregistered)

    For me the worst part is the block style. It take an effort to even see the real code buried in the comment.

    Something I like better than comments is whitespace. I like 120 character wide code plenty of blank lines separating groups of functionality. Lots of spacing wouldn't be popular in the VT100 days, but this is the 21st century and we've got big wide screens now.

  • Darien H (unregistered) in reply to FredSaw
    FredSaw:
    Funny that this topic should come up now. Today I'm working on an update to existing code, and here's what I found when I opened the source. Looks like the previous coder had his output switch set to "verbose"[...]

    That doesn't look too bad to me. I mean, perhaps the guy figured there may be a future case where someone tries to instantiate everything in a subtly-wrong order, e.g. for code reuse or a test case or something.

  • Franz Kafka (unregistered) in reply to AnonymousTart
    AnonymousTart:
    ChrisB:
    I spotted this in some PHP code the other day:

    // start the session session_start();

    Now can anyone tell me how that comment added any value to the code?

    If I'm writing something in a tinky tonky toy language like PHP, I often won't start by writing a detailed design. I'll think for about 5 minutes, and then write the entire file, using comments for any bits that are boring, and/or can't expand without looking away from the file.

    eg:

    //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.

    On the other hand, maybe whichever colleague wrote the code has evaluated his peers and found that those sorts of comments are required..

    yeah, I do that. It help spot any flow-related errors before i've put more than about 5 minutes into it.

  • JM (unregistered) in reply to Sven
    Sven:
    Welbog:
    Sven:
    Welbog:
    If I've written a rather big method with lots of conditions and loops that might be hard to follow
    Then you need to refactor it. :)
    Except for the fact that a refactored complicated algorithm is still a complicated algorithm and would still need an adequate description of how it is accomplishing the task. Refactoring merely moves the location of such a description.
    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)

    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.

  • (cs)

    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; }

  • (cs) in reply to Darien H
    Darien H:
    That doesn't look too bad to me. I mean, perhaps the guy figured there may be a future case where someone tries to instantiate everything in a subtly-wrong order, e.g. for code reuse or a test case or something.
    I don't mean to be knocking him for giving some useful background information. It's just the verbosity of his approach to it. I can condense it down to one line.

    His comments: // At what point does this.Controller get set and from where? Answer: // Default.aspx.cs invokes the Controller property set method defined above; it // does so from its DisplayPatientSummary() method which is invoked from its // page_load routine. // This works because the page_load method of a page gets invoked before // the page_load method of any controls it contains.

    My refactoring of his comments: // NOTE: this.Controller initialized in Default.aspx page_load().

    A developer should already know the order of initialization of a page and its contained controls, and if he needs more details he will look at Default.aspx's page_load() and see that it calls the routine DisplayPatientSummary().

  • (cs) in reply to Vechni 
    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);
  • Former Demon (unregistered)

    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.

  • YourMoFoFriend (unregistered) in reply to Aaron
    Aaron:
    If given a choice between superfluous over-commenting and no commenting (or not enough) I'll take the over-commenting any day of the week. You can always delete unnecessary comment blocks if they're that annoying.

    Besides, isn't complaining about this like complaining about someone who compulsively uses their turn signals after checking their blind spots when changing lanes? I mean -- I agree that in this case the commenting was grossly unnecessary; but I can think of far worse crimes.... coding in VB for example!

    The trolls are at it again :( Same goes for this: "Error handling in VB - The real WTF!"

    The real WTF are those who take a discussion about commenting techniques and turn it into a VB bash. WTF?

    P.S. that was a good WTF regardless of the language. P.P.S. If you need an explanation of what's going on in that sub, you're probably in the wrong field...

  • Bejesus (unregistered) in reply to PACE
    PACE:
    commenter:
    In my opinion, when commenting code directly, just tell us why you're formatting a zipcode as a float or dividing the social security number by 6, or that a bug was fixed here. There is no real need to duplicate the line of code in English, regardless of what college teaches you. Simple methods don't need block in-line comments.
    I disagree. While simple methods like the one above would not need in-line comments, they're still helpful even if you are not doing something obscure, just toi describe WHAT you are doing - not HOW. So it is easier to find a specific position or work on someone else's code.

    benj

    Good god no. The only time you should need comments is to explain the obscure quirks, otherwise your code is poorly factored or you pick stupid method and variable names.

    The main drawback of liberally splashing frivolous comments everywhere is that NOONE, EVER keeps them up to date. For that reason alone keep them sparse and just write decent code. Even the //bug 897123 fixed here ones are utterly pointless, that's what version control systems are for.

Leave a comment on “The Road to Hell”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article