Forgot your password?
typodupeerror
Programming

If the Comments Are Ugly, the Code Is Ugly 660

Posted by CmdrTaco
from the what's-wrong-with-minimalism dept.
itwbennett writes "What do your comments say about your code? Do grammatical errors in comments point to even bigger errors in code? That's what Esther Schindler contends in a recent blog post. 'Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail,' says Schindler. 'Someone who writes software must be a nit-picker, or the code won't work ... Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses) indicate that the developer probably didn't understand what he was doing.'"
This discussion has been archived. No new comments can be posted.

If the Comments Are Ugly, the Code Is Ugly

Comments Filter:
  • by Oxford_Comma_Lover (1679530) on Monday November 16, 2009 @11:33AM (#30116558)
    An explanation may be long if it is explaining something complex that the code is doing. A long-winded comment may also be a precise one, rather than a general one: rather than an excuse, this may be an explanation.
    • I once coded a function that varied depending on what quadrant (+x,+y; -x, +y; -x,-y; +x,-y) it was in. I couldn't get it to work right in the second quadrant, but finally got it working by chance and said so in my comments. The code worked, but I didn't understand why and said so. Is that bad coding? It worked!

      • Re: (Score:3, Insightful)

        by cream wobbly (1102689)

        It's good prototype code, but it's bad release code.

        Was it mathematically different code for each quadrant, or was it conceptually different? In other words, why couldn't you pull the code from the fourth into the second, and swap x and y?

      • by Anonymous Coward on Monday November 16, 2009 @11:43AM (#30116724)

        It worked!

        Are you sure about that? Did you really have enough of an understanding of the conditions to make that statement?

        Chances are, it worked in the subset of cases you understood, and maybe in the subset of cases that the app needed at the time. In the future, though, all bets are off ...

        • Re: (Score:3, Insightful)

          by ardle (523599)
          If the poster could have got the code working in all cases, rather than (apparently) some special case, do you not think he would have written the best possible code and not added a comment to say otherwise?
          I think you are following a "false" (i.e. unlikely enough to be a bit absurd) argument here.
          And hats off to the coder with humanity enough to make other coders' jobs easier if things should get to the point of having to fix said code: at least we know where to look first.

          First they came for the project managers...

      • Re: (Score:2, Insightful)

        by ircmaxell (1117387)
        The thing that I find a lot of developers don't understand is the difference between "Good" and "Good Enough"...

        In your example, the code you got working for -x, +y may not have been "Good", but if it passes the Unit Tests, then how is it really bad? Could it be optimized? Sure...

        Those that seek perfection are destined to a life of search. Those that seek 'working' are destined to a life of success...
        • Re: (Score:3, Insightful)

          by Anonymous Coward

          That's true with anything, though. There often comes a point at which further improvements just aren't worth the effort, no matter what product you're working with. With rare exception, where tolerances in engineering are extremely slim, your work only needs to fall within the tolerances of the person you're working for.

          Now, if you're a good coder, and your code is already pretty 'perfect', that's great. Many programs benefit from optimization even if they worked satisfactorily to begin with, too. Don't exp

        • by Abcd1234 (188840) on Monday November 16, 2009 @12:00PM (#30117028) Homepage

          In your example, the code you got working for -x, +y may not have been "Good", but if it passes the Unit Tests, then how is it really bad?

          How is it bad?? Christ, the metric for "good" code isn't that it simply "works". It also needs to be readable, comprehensible, and maintainable. If you can't understand how your own code works, it's bloody obvious it fails on at least one of those metrics.

          Besides which, unless you are 100% positive that your unit test covers *all* cases, the fact that your code passes tells you nothing about it's correctness.

          You know, back in my university days, we used to scoff at the morons in the labs who would, quite literally, randomly hack their projects until they worked. I never dreamed that some would consider that a valid development methodology out in the real world. Apparently there *is* a dark side to a high-quality unit test suite... it gives idiots a false sense of security and justifies their idiotic development practices.

        • by YXdr (1396565) on Monday November 16, 2009 @12:08PM (#30117134)

          ... but if it passes the Unit Tests ...

          That kinda presumes that the unit tests are good, doesn't it? Which means that somewhere, somehow, somebody has to know what problem they are trying to solve.

          Defining 'good enough' is really tough. I've seen perfectionists get bogged down, but even more often, I've seen folks that invoke the 'it's good enough' mantra as a cover for sloppiness and incompetence.

      • by Frequency Domain (601421) on Monday November 16, 2009 @11:49AM (#30116852)

        I once coded a function that varied depending on what quadrant (+x,+y; -x, +y; -x,-y; +x,-y) it was in. I couldn't get it to work right in the second quadrant, but finally got it working by chance and said so in my comments. The code worked, but I didn't understand why and said so. Is that bad coding? It worked!

        If you don't understand why it worked, then you don't know how it worked. Consequently, you have no idea under what circumstances it won't work. Unless your unit tests enumerated every possible set of inputs, you don't actually know it worked. Just because code works for some inputs doesn't mean it works.

      • by Abcd1234 (188840) on Monday November 16, 2009 @11:51AM (#30116892) Homepage

        The code worked, but I didn't understand why and said so. Is that bad coding? It worked!

        Yes. It's bad coding. Very very bad coding. And, no offense, but it indicates intellectual laziness on your part.

        Any developer worth their salt would spend the time to understand *why* their code is mysteriously working, rather than just throwing up their hands and moving on, as a) it might be working for your test cases but still be incorrect, and b) anyone coming along later will be hosed, as if you couldn't understand it, there's a good chance they won't be able to, either. And of course, d) any developer worth their salt *wants* to know why their code is working, simply because it's interesting and *part of their job*.

        • by characterZer0 (138196) on Monday November 16, 2009 @11:59AM (#30117016)

          Unless your code is running in IE5 or IE6. Then you get it to work by chance, and do not ever touch it again.

        • by clone53421 (1310749) on Monday November 16, 2009 @12:08PM (#30117132) Journal

          On the basis of your username, I'm perplexed as to why you somehow failed to properly letter the items of your list. Perhaps "c) ???" should have come in front of "d) Profit!" (well, a rather long and windy version of "profit", but boils down to it basically)?

          Inb4 comments about my failure to count down from 5.

          • Re: (Score:3, Informative)

            by Abcd1234 (188840)

            On the basis of your username, I'm perplexed as to why you somehow failed to properly letter the items of your list. Perhaps "c) ???" should have come in front of "d) Profit!" (well, a rather long and windy version of "profit", but boils down to it basically)?

            ROFL, because I'm a moron, that's why. Honestly, is that so hard to understand?

        • you often wind up using certain functions heavily that reveal themselves to have strange quirks

          since these functions are effectively black boxes that your average developer has no legal ability to understand deeper, you have to leave it at that

          blaming the coder for being unable to know why something works in such a situation would be fundamentalist in attitude on your part

          yes, you should understand everything you write in code, but you also need a job to put food in your mouth and a roof over your head. not

          • Re: (Score:3, Insightful)

            by Abcd1234 (188840)

            you often wind up using certain functions heavily that reveal themselves to have strange quirks

            since these functions are effectively black boxes that your average developer has no legal ability to understand deeper, you have to leave it at that

            Ah, external dependencies are a very different thing, though.

            If I'm coding against an external library, and it behaves unexpectedly, there's little I can do but to document the issue, explain that the code is written to work around a mysterious library bug, and move o

      • by Esther Schindler (16185) <esther@bitranch.com> on Monday November 16, 2009 @11:54AM (#30116928) Homepage

        I agree with cream wobbly that it's good prototype code but bad release code. On the other hand it's okay with me that you explained the difficulty in the comments because that fulfills the purpose: You're communicating with the next developer who looks at the code.

        If you managed to get it to work (you think, anyhow), it may still be buggy; and the "Well, I THINK so..." in the comments will be an arrow to "probable source of application meltdown" for someone who comes in to debug.

        There's a difference between writing a good explanation that happens to be long, and a rambling list of excuses. Yours sounds like the former. IMHO.

      • Re: (Score:3, Informative)

        by tgrigsby (164308)

        As a programming "old coot", I'd say that if you didn't understand why, then yes, by definition that's bad coding. You need to understand the problem before you can fully address the problem. And if the solution is complex, your comment shouldn't say, "Wow! I can't believe this worked. Good luck if you need to change it!" It should instead educate those that come behind you. Comments should be an aid to understand not only the code but the problem domain addressed by the code. It's a means of recordi

    • by gstoddart (321705) on Monday November 16, 2009 @11:44AM (#30116746) Homepage

      An explanation may be long if it is explaining something complex that the code is doing. A long-winded comment may also be a precise one, rather than a general one: rather than an excuse, this may be an explanation.

      I have known several people who point out that if it really does require that complicated of an explanation, you might need to re-factor your code and make it less arcane. Of course, not everything can be simplified to the point where it's obvious when you read it, but I've definitely seen a lot of code that could/did benefit from changing it to make it more straight-forward and readable.

      In general though, I agree with the article -- I've known more than a few developers who barely if ever comment code, and claim that it should be obvious from the code. As such, their comments (what there are) tend to be fairly random and not helpful. I once saw a comment that said "die lamer die" with no explanation whatsoever. "Add 1 to count" is also fairly useless.

      Me, I always write the comment for a function/method before I've started writing the body of the method. Because, even if it's just me maintaining the code, I want to know what it was there for in the first place.

      Cheers

    • by Marillion (33728) <ericbardes@gm a i l .com> on Monday November 16, 2009 @11:45AM (#30116768)

      I've always subscribed to the theory that the code explains WHAT a program should do clearly enough that even a computer understands it.

      Comments should fill in the gaps and answer the questions of WHY and HOW. For example, if I'm using a common pattern or idiom, I like to highlight that. I like to use the Delegation Pattern when doing SAX parsing of XML in Java. Rather that explain what the Delegation Pattern is about, I'll just cite the pattern name, add a link, and explain the nuances of that particular implementation and move on.

      • by Kell Bengal (711123) on Monday November 16, 2009 @11:54AM (#30116934)
        I agree to a limit. My philosophy is to code the comments, rather than comment the code.

        Comments, for me, serve as a design tool as much as an aid to understanding. You can very quickly understand what my programs are supposed to do by reading the comments; not because my code is hard to understand, but because the comments describe its function as a narrative.

        Of course, if you can't understand what the code does without reading the comments, you're doing something wrong. Once coded, the comments exist to extend and clarify what the code is doing, as well as adding meta data about how things like numerical constants were calculated.
        • Re: (Score:3, Interesting)

          by clone53421 (1310749)

          True. Furthermore, it's arguably proper, when implementing a particularly clever and streamlined hack (i.e. impossible to decipher, when debugging the code), to set it off from the code visually and then follow it with a commented-out block of code which does exactly the same thing, albeit slower or less efficiently, and which will be much easier to understand.

          As a bonus, if the code must later be changed and the original hack would no longer be possible in the new functionality of the code, the procedure h

        • by mjschultz (819188) on Monday November 16, 2009 @12:18PM (#30117304) Homepage

          I've gotten into the habit of commenting first, coding second. It is especially useful in complex systems.

          I find that if I write the high level logic in comments of all the functions I'm going to write, it helps me find where I should break out repeated logic and solidifies the design. Once everything has been commented, I can go back and write the code.

          This lets me know what the variables are going to be and can name them appropriately (why name it `i` when I can call is `block_index`). I don't lose the big picture of what needs to get done. It gives me targets to meet and stopping points at the end of the day (a sense of accomplishment and goals for tomorrow is *really* nice). Future coders can read my comments and see what I was thinking (this has actually happened to me). As a bonus, I can worry more about corner cases as I'm writing the code instead of creating corner cases to worry about later.

          I've done it with a Flash memory interface, O/S memory manager, and a kernel module. Each time I've finished, even if it isn't the best code in the world, I know that if the next person reads the comments, they'll know what I was thinking.

          Better code all around.

    • by eln (21727) on Monday November 16, 2009 @11:49AM (#30116838) Homepage
      Precisely. Comments about code that the developer himself doesn't understand, usually because he employed some nasty hack and he's not sure exactly why it worked, are usually short and contain the word "magic" in them.

      For example:

      /* Magic happens here*/
      /* Black magic */
      /* Some particularly dark black magic occurs here */
      /* I'm not sure why this works, but it does */
      /* I went on a vodka bender last night, and this was on my screen when I woke up. I don't know what it is, but it compiles, so let's ship the fucker. We'll call it Vista. */
      • by clone53421 (1310749) on Monday November 16, 2009 @12:16PM (#30117260) Journal

        I went on a vodka bender last night, and this was on my screen when I woke up.

        I've had that happen to me a few times. It's a bit unsettling, I assure you.

        What's even more unsettling is waking up with a full plate of hash browns and eggs next to my bed, and having no recollection of ever making them. It did make for a nice breakfast, though. Perhaps I should do it more often.

      • Re: (Score:3, Funny)

        by Unequivocal (155957)

        We ran across a classic one of these. A application we developed in 1992 stopped working in 1994 for some unknown reason. After a few days of heinous debugging to build a test case, we come across a line of code headed with this comment: /* this will not work - jr */

        We fix that line so it will work, and all have a good laugh later. At the time it was pretty frustrating as I recall. I'm still good friends with JR by the way.

    • by Moraelin (679338) on Monday November 16, 2009 @12:07PM (#30117126) Journal

      Or it could be just an indication of a management failure.

      A couple of years ago I was brought in to save a project that was hopelessly behind schedule and getting nowhere. Pretty quickly I got the idea that whenever I check something into CVS, it gets re-checked by a really helpful girl there, richly decorated with comments. (Now I do comment classes and methods extensively, as well as places where higher elven magic was used, but I do _not_ write stuff like that now I'm iterating through a node's children. If you need a comment to understand that "for" loop, then there's something deeper wrong with my code.)

      But, anyway, stuff like a line that said "if (currentNode.isRootNode())" had been decorated with the obviously helpful comment "// when the current node is the root node". I'm still at a loss as to what extra info is conveyed by that comment, since just reading the code out loud gets you almost the same sentence and definitely the same meaning.

      And it went like that for every single line. Every single assignment, trivial loop, etc, was dutifully duplicated in that line's comment.

      Turns out, they were asked to comment their code extensively, and judged basically by quantity. So she was just abiding by the rules.

  • Comments are good (Score:5, Insightful)

    by Anonymous Coward on Monday November 16, 2009 @11:33AM (#30116564)

    Comments are good for many reasons:
    1. Showing the next person what you were doing.
    2. When you have to explain what you are doing, it helps you to discover possible errors in your code. Particularly logic errors.
    3. It helps you if you have to come back and look at it in a few years so you will immediately have an explanation of what you were doing.

    Of course for those of us who code perfectly the first time, they aren't really needed. :-)

    • by e70838 (976799) on Monday November 16, 2009 @12:14PM (#30117236)
      Comments shall be avoided as much as possible :
      1) the code shall be simple and the name of variables and methods shall be self explanatory in most cases. When this is applied, there remains very few to explain at the code level. The reader of your code is not dumber than you (except when he is your boss).
      2) the more you add comment lines, the less lines of code you can see on your screen. When you start scrolling continously, the speed of code production reduces significantly.
      3) comments introduce a redundancy. What shall be trusted when code and comment differs. Is the code wrong or the comment outdated ?
      4) comments in the code are often used as a substitute for a global software architecture description. In the example of the java api documentation, it is very hard to get a global view of a class with only class comments, we need additional documentation (the tutorials).
      Joke apart, code often contains many comments because it shall comply to quality standards, but strangely, the parts of the code that are difficult to understand are generally not commented. It is a variant of Murphy law that is very useful when auditing code.
    • Re: (Score:3, Insightful)

      by digitig (1056110)

      Comments are good for many reasons: 1. Showing the next person what you were doing. 2. When you have to explain what you are doing, it helps you to discover possible errors in your code. Particularly logic errors. 3. It helps you if you have to come back and look at it in a few years so you will immediately have an explanation of what you were doing.

      4. Cross-referencing the specification, for reverse traceability.

      Of course for those of us who code perfectly the first time, they aren't really needed. :-)

      Requirements never change, do they?

  • Co-workers (Score:5, Insightful)

    by Tomun (144651) on Monday November 16, 2009 @11:35AM (#30116574)

    Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing.'

    Or that he's forced to work with people that don't.

    • Re:Co-workers (Score:5, Insightful)

      by garcia (6573) on Monday November 16, 2009 @11:43AM (#30116712) Homepage

      Or he's being a good employee and doing the right thing to ensure:

      1. One to three years from now when the code needs to be revisited by him that he can quickly assess the code without thinking about it too much.

      2. Long after he's gone another employee can come across the code and easily understand what was done and why.

      3. Comments, to me, are like writing out all the steps in a math problem. Just because you arrived at the correct answer on the face of things does not mean that you understood what you did. Documentation proves, in many cases, that you did in fact know what the fuck you were doing.

      --

      If you don't like comments, fold them out of the way and be done with it. I just don't see the problem here.

    • by ari_j (90255) on Monday November 16, 2009 @11:44AM (#30116744)
      I always write long comments that either have no relation to the surrounding code or tell outright lies about it.
      • by Carewolf (581105) on Monday November 16, 2009 @12:17PM (#30117286) Homepage

        I always write long comments that either have no relation to the surrounding code or tell outright lies about it.

        Did you by any chance write ALSA? And did you write your long deceitfull unrelated comments in an APIDOX compatible format which later got published as a sort of documentation?

        Because that.. would explain so much...

    • Or that he's writing code that will be read by someone he doesn't get to explain the code to.

  • by Russ Nelson (33911) <slashdot@russnelson.com> on Monday November 16, 2009 @11:36AM (#30116586) Homepage

    Comments exist NOT to explain the existing code, but to explain all the other code that could have been written, but wasn't. They also point to things like test cases (which if your language doesn't suck, you can put in line), and explanatory standards documented elsewhere.

  • by i.r.id10t (595143) on Monday November 16, 2009 @11:37AM (#30116600)

    For me, it is bad spelling in variables and such. Or correct but "alternative" spellings - like honor_no_cache vs. honour_no_cache

    Working with fellow students in a group (with one student being from England) brought this out, and in general poor spelling - category vs. catagory, etc.

    Fortunately mostly fixable with find/replace, but still a bear to deal with.

    • by pem (1013437)
      Yes, back in the 90's, I worked with a junior developer who thought that everyVariableMustTellItsOwnStoryIncludingItsLifeHistoryInItsName. He misspelled one of these gems, and I was grepping for a solid half hour before I figured out why I couldn't locate it, after glancing at the name in one of the source files.
    • by cream wobbly (1102689) on Monday November 16, 2009 @11:49AM (#30116854)

      I refer you to... the infamous "HTTP_REFERER".

    • Re: (Score:3, Informative)

      by Mr. DOS (1276020)

      America isn't the only country in the world. In England and Canada, "honour" is the correct spelling and "honor" is the "alternative" spelling.

            --- Mr. DOS

  • Seems reasonable (Score:5, Interesting)

    by jgtg32a (1173373) on Monday November 16, 2009 @11:37AM (#30116610)
    Comments do require a bit of effort and time commitment. If you are willing to spend time on the comments your most likely going to spend more time working the code itself.
  • by tedgyz (515156) * on Monday November 16, 2009 @11:40AM (#30116670) Homepage

    Comments are for wimps.

  • by JoshuaZ (1134087) on Monday November 16, 2009 @11:40AM (#30116672) Homepage
    I sometimes write code for number theory algorithms. Often short-cuts and little speed ups have long proofs to justify why they work. If I expect the code to be used/read by other people I'll often include these explanations (and so I don't need to bother convincing myself later if I look at the code a year later). There's nothing wrong with long comments. Moreover, given a negative attitude towards long comments, many bad programmers will likely simply respond by not commenting their code at all. That's not good.
    • by dkleinsc (563838) on Monday November 16, 2009 @11:50AM (#30116862) Homepage

      Often better than including the full explanation inline is: "Proof that this works can be found ...". Yes, it's one more reference to look up, but some of the algorithms in, say, Knuth, are long and complex proofs that really will interrupt your code reading if included inline.

      A lot of good comments answer one of these questions:
        - Why couldn't this be simplified?
        - What special case is this trying to handle?
        - This looks weird. Why is it right?
        - What expectations are we demanding from elsewhere in the code?

      A situation where I find myself asking any of those questions and no comment is present can be nightmarish.

      • Re: (Score:3, Insightful)

        by darthflo (1095225) *

        Linked stuff has an annoying tendency to not be available when you most need it, be it expired domain names, dying servers or even reading the comment in a WiFi-less coffe shop. Cited books tend to only be available in a different edition than referenced.
        But the solution's quite simple: GP, keep on commenting as long as necessary. IDEs and even rather simple editors have allowed coders to collapse comment blocks for several generations now. Long comments are no problem.

  • Well, duh. (Score:5, Funny)

    by mobby_6kl (668092) on Monday November 16, 2009 @11:40AM (#30116680)

    That's also why I don't comment my code.

  • by TheRaven64 (641858) on Monday November 16, 2009 @11:41AM (#30116694) Journal

    It should be obvious what the code is doing just from reading it. If it isn't, then the code should usually be refactored. Comments are for explaining why the code is doing that. If your grammar is poor in the English then it's probably poor in the code too (unless you are not a native speaker). If you make spelling errors in comments then you probably do in code too. The compiler will catch some of these, but when you accidentally type the name of an instance variable or a global instead of a local, it won't spot it. If you're not checking your comments for this kind of error, you're probably not checking your code for it either.

    Just as with online comments, poor grammar displays a lack of care. Hopefully, more people will be reading your comments than will be writing them. A little effort in writing them can save a lot of effort in reading them. If someone on the Internet thinks that their time is worth so much more than their readers' time then that just makes them an asshat[1]. If a programmer thinks his or her time is so much more valuable than that of people maintaining the code then he or she is a terrible programmer.

    [1] I am fully aware of the universal law that means that, by writing this, my post will have a significantly above average number of typos. Please be nice...

  • This seems like a no-brainer to me. Sloppy people are sloppy and stupid people are stupid, how is this not evident? The only difference is that a lot of bugs are obvuous, when the code fails to run or runs is an unexpected way, while the bad comments won't stop the code from working, only from being understood.

    There are a lot of times I'll see slashdot comments like "you might loose your mind" and I think "I hope that guy's not a programmer." Loosing your mind is quite a different thing than losing it, and

  • by AmiMoJo (196126) <mojo@NOspAm.world3.net> on Monday November 16, 2009 @11:44AM (#30116734) Homepage

    English is not most people's first language. Be glad they want to write comments in English at all.

  • Or at least sloppy thinking. I have no idea why this is, but as anyone who has looked at internet blogs can attest, the people who can't be bothered with proper spelling, grammar, punctuation or capitalization, or who can't differentiate between "loose" and "lose" are also (usually) the biggest idiots.

  • Yes, spelling and grammar in comments are important for understanding, and proper spelling in variable names in particular makes it easier for developers after you to follow and track through code. However, I disagree with the generalization that long comments always mean you don't know what you are doing. Most of my code comments are 1-liners, but I always leave long comments for function headers so everyone is clear on what the inputs are. I also leave larger comments for equations that aren't immediat
  • by Yvan256 (722131) on Monday November 16, 2009 @11:45AM (#30116776) Homepage Journal

    I always try to comment my code, but then the compiler keeps telling me there's no code to compile.

  • by monkeySauce (562927) on Monday November 16, 2009 @11:45AM (#30116778) Journal
    "Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing.'"

    That's right, I'm an expert and I keep my code comments short and sweet. Observe:

    // This function kicks ass.

    function kick_ass()
    {
    ...

    // This following code is like Chuck Norris. It doesn't know how to fail.

    while(true)
    {
    ...
  • by JustNiz (692889) on Monday November 16, 2009 @11:50AM (#30116868)

    From 30 years of developing software, I've found time and time again that it actually does seem that people who don't know or care about the difference between "their" and "they're" are also too sloppy, unintelligent or just not anal enough to write clean, supportable and robust code.

    However I feel we do need to make more allowance than the article's author did for people who did not learn English as a first language.

  • by travdaddy (527149) <travo AT linuxmail DOT org> on Monday November 16, 2009 @11:50AM (#30116872)
    If comments even exist, then the code is ugly. Code should document itself.

    (Any good Perl programmer knows this.)
  • by Baby Duck (176251) on Monday November 16, 2009 @12:05PM (#30117088) Homepage
    If I have a long comment explaining "magic", 99 times out of 100 it's because I'm being forced to interface with a bad API which THAT CODER didn't properly understand. Glaring errors in the documentation, unexpected outputs, unexpected hangups ... these are my duty to comment about. Of course I don't understand why the API is malfunctioning ... it's a BLACK BOX. My employer might be too much of a cheapskate to purchase product support to troubleshoot the API. Or the vendor might charge outrageous support fees for their mess ups. I cannot switch to a different API, because I do not have the authority to make that decision. My comments are self-defense when backed up against the wall. It does nothing to gauge my programming ability.
  • by wandazulu (265281) on Monday November 16, 2009 @12:05PM (#30117090)

    The granddaddy of WTF comments must come from the original Unix source, written by none other than Dennis Ritchie: /*
              * If the new process paused because it was
              * swapped out, set the stack level to the last call
              * to savu(u_ssav). This means that the return
              * which is executed immediately after the call to aretu
              * actually returns from the last routine which did
              * the savu.
              *
              * You are not expected to understand this.
              */
            if(rp->p_flag&SSWAP) {
                    rp->p_flag =& ~SSWAP;
                    aretu(u.u_ssav);
            }

    So here's an example of a comment that does an excellent (I assume) job of explaining why the code is doing what it's doing, yet the whole thing is so complicated that Ritchie even needed to acknowledge that the comment probably wasn't going to be of much help either with an amusing, and now somewhat famous, statement.

    • An addition (Score:3, Informative)

      by wandazulu (265281)

      Dennis Ritchie has a whole page of comments [bell-labs.com] in the Unix source code, and what information they convey.

    • Re: (Score:3, Insightful)

      by gstoddart (321705)

      So here's an example of a comment that does an excellent (I assume) job of explaining why the code is doing what it's doing, yet the whole thing is so complicated that Ritchie even needed to acknowledge that the comment probably wasn't going to be of much help either with an amusing, and now somewhat famous, statement.

      In fairness to Ritchie, he was programming on bare metal and breaking new ground. OS level code talking directly to hardware can get pretty grotty because of all of the vagaries that can be g

    • Re: (Score:3, Informative)

      by syousef (465911)

      So here's an example of a comment that does an excellent (I assume) job of explaining why the code is doing what it's doing, yet the whole thing is so complicated that Ritchie even needed to acknowledge that the comment probably wasn't going to be of much help either with an amusing, and now somewhat famous, statement.

      Sorry but that is just a piss poor comment and there is no excuse for glorifying it. If it's that complex, he needs to refer back to a particular section of a particular version of a design do

      • by syousef (465911)

        I hope I never work with or have to deal with code from whoever thought that was flamebait.

  • OT on long comments (Score:5, Interesting)

    by FrankSchwab (675585) on Monday November 16, 2009 @12:09PM (#30117144) Journal
    Being as this is devolving into a discussion of long comments, rather than a discussion of whether mispellings in comments indicate a lack of attention to detail in coding, I thought I'd throw in something.

    To maintain some sense of topicality: I don't particularly agree with the blog post. As someone with good English skills, I've read a lot of code where the English language skills (and thus spelling and grammar in the comments) of the coder are below mine, but their skills in the computer language at issue are superior to mine. Frankly, there's a far greater relationship between accuracy of the comments (do they actually describe what the code does) and the quality of the code, than there is between spelling, subject-verb agreement, and number of spaces after a period and the quality of the code. This relationship does follow the blog author's contention about coders needing to be nit-pickers.

    Occasionally in my coding, I write a novel in the function header. Generally, this isn't because I don't understand the problem so much as its because I do understand the problem. I've spent hours or days understanding the problem, and the particular necessray function that implements the solution, and I don't relish spending hours or days 6 months in the future remembering what I know today. The interesting thing is that, most of the time, the novel is multiple times larger than the function - 50 lines of comment for a 20 NCLOC function isn't unheard of.

    In my specialty (embedded systems, with especially tight hardware integration), there are functions that need to be written that deal with extraordinarily complex situations. Many times, the bare code tells a misleadingly simple tale - "do this, that, and the other thing", rather than (as Russ Nelson pointed out above)

    but to explain all the other code that could have been written, but wasn't

    . Oftentimes, the novel is there to explain all the ways to trip up in this 20-line function - e.g. unspecified hardware dependencies, subtle system dependencies, unobvious race conditions. Sometimes its there to explain why, no matter how wrong the function appears, it is actually correct.

  • by SombreReptile (455564) on Monday November 16, 2009 @12:12PM (#30117196)

    I cut text from Finnish language websites and paste it in as comments. I don't know what it says, but it looks really cool.

  • by Tablizer (95088) on Monday November 16, 2009 @12:20PM (#30117324) Journal

    Everybody has their little "pet signposts" that they use to make wider conclusions. Although there may be small truths to some of them, relying on weak correlations is generally a dangerous way to make conclusions. Good programming involves a wide variety of skills. To focus on a few narrow factors does a disservice to this fact.

    For example, I sometimes put in long comments because the business rules themselves are convoluted. Programming logic cannot make a silk purse out of a sow's ear. Ugly biz rules are ugly biz rules and are not explainable in just a few lines. It's outside of the scope of my duties to clean up the business practices (other than pointing them out sometimes).

    I agree that long comments can serve as a yellow alert to stop and think. But that does not mean that all long comments are inherently a sign of flawed code. The author is being a drama queen via exaggeration. And perhaps it's part piety: I am a careful comment-speller, so you should be also.
         

  • by cwills (200262) on Monday November 16, 2009 @12:23PM (#30117366)
    The whole purpose of comments is to explain the code so that future maintainers (including the author of the code) can easily understand what is going on. If done right, a maintainer can pick up a module and come up to speed as to what the code does, why it does it, and any thing else that might trip them up. Comments need to capture the developers thoughts from when the code was being designed and written. The reasoning and ideas behind an algorithm that took several months to design cannot be truly captured with a 3 line comment and 25 lines of code.

    I feel that comments can be broken into four types:

    1. Boiler plate front matter. These are the comments that are required by the coding standards of the shop. Usually contains copyright notices, author's name, list of changes, etc.
    2. Specification and reference comments. A list of the external references, such as the formal specification for the code, a bibliography for the algorithms used, etc.
    3. Block comments. These should describe the intent of a larger block of code. The reader should be able to take all the block comments from a program and have a good understanding what the entire program does. Block comments should describe the what and why. Block comments should also describe any gotchas, or special conditions that the maintainer needs to be aware of.
    4. Line comments. Should describe the purpose of a small number of statements. Line comments should not merely echo the action of the code itself, but describe what is happening and how the particular action relates to the rest of the program.

      i += 4; /* Increment i by 4 */ BAD comment

      i += 4; /* Ignore the first 4 fields */ Better

  • Coding Drunk (Score:3, Interesting)

    by twmcneil (942300) on Monday November 16, 2009 @12:31PM (#30117576)
    I usually comment much more (and need to) when I'm coding drunk. That also explains the excessive use of the word "Fuck" in my comments. But even drunk, I know the difference between their, there and they're.
    • Re: (Score:3, Interesting)

      by sanosuke001 (640243)
      A professor I had in college said that the best time to code is when you have a few beers in you and that if we weren't a freshmen class he'd hold our class at the local bar.

      Such a cool teacher... and the Computer Science head now...
  • by lophophore (4087) on Monday November 16, 2009 @01:17PM (#30118498) Homepage

    Perfectly working, syntactically and logically correct code can be utter crap if it is not maintainable.

    Years ago, a very smart man told me that I was not writing code for the compiler, I was writing code for the next poor slob that had to work on it. Let's face it, most source code is going to be subject to rework or maintenance over its life span, so let's do what we can to make that next developer productive. The key to this is reasonable commenting.

    One of the best ways I know of to teach developers to write maintainable code is to have them do support and maintenance for a while. Developers learn quickly which styles work for maintenance, and which ones don't.

    As far as I am concerned, source code needs to look good as well as compile. So I would go one step beyond TFA to say that style, indentation, proper symbol names, use of constants where appropriate, and (yes) proper commenting are all good indicators of quality in source code.

  • The reality... (Score:3, Interesting)

    by TemporalBeing (803363) <bm_witness&yahoo,com> on Monday November 16, 2009 @02:23PM (#30119804) Homepage Journal
    The reality is that comments tell what the code ought to do; while the code only shows what it actually does.

    I tend to write comments of varying lengths - sometimes, writing longer comments not for my own benefit, but for the benefit of the next coder - someone who may or may not have my understanding of the system or code; and more likely than not, either won't have the time to learn the code 100% in-and-out, or are not up to the same par. So sometimes, I will write a large comment block on an important thing in the code - so that they (whoever they are) will be able to understand it quite quickly. However, that is (as it should be) quite few and far between; sometimes documenting complex logic from elsewhere in the system that I have no control over but the programmer needs to be able to understand.

    Of course, there is also the typical PHB managers who evaluate their programmers based on LOC, SLOC, and CLOC (LOC = SLOC + CLOC), and look for an even distribution of SLOC/CLOC - e.g. SLOC/CLOC = 1. In some cases that is good; but in most it is not.

    All in all, you can't tell how good the program is by just general comments or comment analysis.

    BUT if you are sloppy in your comments (grammar, spelling, etc.), you have probably been sloppy in your code. To that end, I do very well agree with the article.

    P.S. BTW, I've been in 3 positions where I have replaced people. One fired; one died; and one quit. In two of those three, the original developer was no longer available for inquiry; in the third, it was possible but not easy and only for a short time after he left.
  • by presidenteloco (659168) on Monday November 16, 2009 @02:42PM (#30120170)

    Worst: Originally erroneous or out of date therefore erroneous comments. Actively destructive to comprehension of the program, and once detected, causes all other comments in the program to be rejected as untrustworthy and worse than useless. "Comment Bug".

    2nd Worst: No comments - indicates the developer either does not understand the purpose or method in their madness, or is lazy and sloppy. Either is very bad.

    3rd worst: Redundant comments: /** Gets the Foo! */ Foo getFoo() See Java api documentation for prime examples.

    I would much rather read a long rambling philosophical comment that was essentially correct and did add some information than to deal with any of the above slackerware.

  • by syntap (242090) on Monday November 16, 2009 @06:27PM (#30123574)

    Whoever is criticizing grammar in comments obviously never had to look through legacy code and ask him/herself "WTF was this developer thinking?!" Or better yet, looking at one's own code written five years earlier and asked him/herself "WTF was I thinking?!" In those cases, any comments at all will provide clues.

    We should be encouraging coders to use comments _at all_, not giving incentive to shortchange it because they are going to be graded on stuff the compiler ignores. Any coder stuck with making changes to old code will be very thankful to see long-winded comments.

    Let's not forget that code is read many more times than it is written. Yes, it would be nice to have precise comments that tell all. But if a coder wants to go into detail then friggin let him, to suggest otherwise is just dumb.

The ideal voice for radio may be defined as showing no substance, no sex, no owner, and a message of importance for every housewife. -- Harry V. Wade

Working...