Forgot your password?
typodupeerror
Programming

Myths About Code Comments 580

Posted by timothy
from the myth-conceptions dept.
theodp writes "Jason Baker gives his take on the biggest misconceptions about code comments: 1) Comments are free ('When you update the code that the comment references, you usually have to update the comment as well'). 2) Comments make code more readable ('by far the most pervasive myth that I've encountered'). 3) You should comment every function, method, class, and module ('documenting something that needs no documentation is universally a bad idea'). 4) Code must always be 'self documenting' ('would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?')."
This discussion has been archived. No new comments can be posted.

Myths About Code Comments

Comments Filter:
  • by yog (19073) * on Friday January 01, 2010 @06:30PM (#30616696) Homepage Journal

    Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented. The price of maintaining comment-free code is well known.

    There is a school of thought among programmers who consider themselves hotshots that if you are not a hotshot you have no business touching their code. The problem with this attitude is that it has little to do with the real world, where people change jobs and programmers inherit someone else's code. If you want to write perfect, comment free code in your perfect little world, go right ahead, but don't expect to make a living at it most of the time.

    It's surprising to me that someone has submitted this as a "news" item. News flash! Everything you know is wrong. Sorry I don't buy that. If you don't comment your code, I won't pay you for it. I'll inform the management that you neglected an important step and don't deserve a good reference. I won't be able to give you the benefit of the doubt when your code doesn't make perfect sense. I'll trash talk your code in front of your colleagues. Look at all the mistakes in this guy's work; I'll sure never recommend him if his resume crosses my desk. We may need to just rewrite this stuff because it's not maintainable as written.

    What's really annoying is when they put comments that don't elucidate the code or their intent; they're just snide little messages from one know-it-all to another. They're too embarrassed to actually explain the code because that implies a level of insecurity they would rather not admit to. So instead they say things like: /* yeah, I don't like this either */
    or
    # hack, to be fixed later

    Wooooo, really helpful comments there. I've seen this sort of thing countless times in my career and most others I know have as well.

    • by Brian Gordon (987471) on Friday January 01, 2010 @06:37PM (#30616736)

      Woooo, business programming. Believe it or not, there are a few applications out there that require performance and cleverness rather than strict convention. I think that a myth of software development is that every line of code should always be simple and easy to understand. Sometimes things are complicated, especially in performance applications.

      • Woooo, business programming. Believe it or not, there are a few applications out there that require performance and cleverness rather than strict convention. I think that a myth of software development is that every line of code should always be simple and easy to understand. Sometimes things are complicated, especially in performance applications

        GP never said that (re:bolded text), and the point you are trying to make makes a strong argument FOR clear, concise comments on code. Good code isn't always easy

        • by DG (989) on Friday January 01, 2010 @07:37PM (#30617178) Homepage Journal

          Indeed.

          Sometimes there is a very good reason for including clever, non-intuitive code in a project. But that clever code needs to be very well documented because the next guy to touch it may not be that clever.

          When in doubt, optimize code for future maintainability and legibility. Hardware gets faster. Programmers don't.

          DG

          • Kernighan (Score:5, Informative)

            by HiggsBison (678319) on Friday January 01, 2010 @07:52PM (#30617302)

            It was Brian Kernighan who pointed out that:
            "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

            • by zill (1690130) on Friday January 01, 2010 @08:07PM (#30617410)
              So I should dumb myself down with a hammer before writing code?

              I'm not sure how I'd reverse the process before debugging though. Maybe I should have thought of that before the hammer came down...
            • Re: (Score:3, Insightful)

              by DLG (14172)

              This is a point I really am trying to make too... The best code you do, the stuff that required you to actually use your brain hard, is going to be hard for YOU to maintain let alone others. You comment based on your own Eureka moments, you document your understanding, and hopefully it lets a person recognize that you were both solving the problem in a reasonable manner, and that your implementation and solution are in sync.

              Beyond that, adding a few lines of code for clarity can also make it easier to debug

          • by pz (113803) on Friday January 01, 2010 @11:04PM (#30618994) Journal

            I can't count the number of times I've written a very carefully researched small handful of lines of code that are either not intuitively obvious, or would leave more questions than they answered when read. When I've spent days demonstrating through thorough measurement that, for example, a certain constant requires a specific value, that fact gets documented with potentially many paragraphs of comments. Not doing so would be irresponsible, and a waste of my time when I tried to understand, months or years hence, why I had written that small handful of lines.

            To quote one of the Ramones who was criticized in an interview for writing songs with only three chords, "yeah, but they're the RIGHT three chords." With music you can feel if the chords are right. With code, sometimes you have to document.

    • by v1 (525388) on Friday January 01, 2010 @06:39PM (#30616748) Homepage Journal

      I find the most important comments are those that tell you WHY something was done the way it was. I do this with my own code when I track down and fix a bug that turns out to be caused by some very subtle effect or easily made mistake. I put the comment there to stop myself (or someone else) from "fixing" / "cleaning it up" later because they don't realize why it's done the way it is. Comments like:

      # yes, 1, not 0. If all four of the lists are allowed to go to 0, we will blow up later with DBZ.

      And having a sometimes very poor memory of code written long ago, this saves me from myself more than others.

      • Re: (Score:3, Insightful)

        by daVinci1980 (73174)

        I say this in a slightly different, but more concise way:

        Comments (and self-documenting code) should tell you "what" and "why", because the code is telling you "how".

    • Re: (Score:3, Insightful)

      by MichaelSmith (789609)

      I work on a really big hunk of C code and one place I would like to see more comments is in the start and end of blocks. This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block and totally stuff up the indenting so its hard to see what is supposed to match to what. This is particularly a problem with importing between branches (my job at the moment) because it can be hard to work out the original intent of the various nested blocks you wind

      • Re: (Score:2, Informative)

        If you're writing in C, do yourself a favour and check out this editor: http://www.geany.org/ [geany.org]

        It's the slickest C editor that I've ever had the pleasure of using. It seems little-known, though, and I don't know why.

        (It handles other stuff than C too, but I haven't used it for any of those yet.)

      • Re: (Score:3, Insightful)

        by Tanuki64 (989726)

        I work on a really big hunk of C code and one place I would like to see more comments is in the start and end of blocks. This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block and totally stuff up the indenting so its hard to see what is supposed to match to what.

        If the only tool you have is a hammer, every problem looks like a nail. You comments are in this case the nail you desperately want to hammer in, when in reality you need a refactoring. And you need to give the idiot, who pastes the additional 1000 lines, a hearty kick in the ass.

      • Re: (Score:3, Insightful)

        by GeckoAddict (1154537)

        This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block

        Your design is horribly wrong.

        so its hard to see what is supposed to match to what

        Branches or not, you need a coding standard, fast.

        Where I work comments get used to abuse people.

        Your development team is in need of some management and/or personal communication skills.

    • by khallow (566160) on Friday January 01, 2010 @06:47PM (#30616790)
      Even the "this is a hack/kludge/abomination unto nature" comments are useful to me. It tells me some starting points for improving the code. Also I write similar comments to remind myself where the iffiest parts of my code are.
      • by 93 Escort Wagon (326346) on Friday January 01, 2010 @07:04PM (#30616928)

        Even the "this is a hack/kludge/abomination unto nature" comments are useful to me. It tells me some starting points for improving the code. Also I write similar comments to remind myself where the iffiest parts of my code are.

        I agree. When I put those sorts of comments in, they are most often notes to myself rather than a legacy left behind for others.

        I prefer to write code that's easily extensible, and in most cases it's what I try to do - but that definitely takes longer than hacking something together (at least for me). Since I'm not the boss, there are times when I've been given direct orders to "just get it done so I can show this to xxxxx, we're never going to need to change this anyway" - and I do it. Down the road I try to fix those when I'm in a slow-ish period; but also, they are valuable reminders when, a year later, the boss comes back and says "can we add yyyyy and zzzzz to that?" because it a) gives me a chance to talk with him about why I prefer writing it right the first time; and b) provides support for telling him why it'll take me a few days to add those features rather than the 1-2 hours he thinks this "minor change" should take.

        On a side note: There's nothing worse than running into someone else's 6-7 year old bit of code containing comments like "hack, important to fix this next revision" - it's too much like finding those silly "under construction" animated gifs on a web page that was last updated in 2003.

    • It's possible to write code that doesn't need any comments. Code where the next person to read it will understand exactly what it does and why, just from the code. The difficult thing is knowing when you've done this and when you've written something confusing. If you can tell the two apart with 100% accuracy, then you can skip writing comments.

      Unfortunately, I've never met a developer that could. I've met quite a few that thought they could, however...

      • Re: (Score:3, Insightful)

        by hedwards (940851)
        OK, this topic is officially over. That's the nub of it, if a programmer could intuit what would be confusing a decade down the road or to another developer that takes over, then you can cut out on the comments. The cost of documentation does exist, but people ought to be thinking twice before putting in overly complicated, absolutely must comment code. Sure some cases require that for legitimate reasons, but most of the time you're doing it wrong, and putting in the comment gives you the opportunity to rec
    • Re: (Score:3, Insightful)

      by WED Fan (911325)
      In your race to be first, you failed to read the article.
    • Re: (Score:3, Insightful)

      by SteveWoz (152247)

      Both the code and the comments should be as understandable as possible. Don't forget that the effort to comment well helps the programmer in his/her own thinking and his/her own understanding of their own code, and helps in development of good code that doesn't have bugs.

    • IMO it boils down to "if it's complicated then comment it, otherwise don't". Unnecessary comments just get in the way. I'd add that lots of code is complicated and "hairy", and thus deserves comments, solely because its author was not skilled enough to create a cleaner solution.
    • by Nelson (1275) on Friday January 01, 2010 @07:46PM (#30617256)

      What did this blog writer actually ever do that's worth a shit? Shouldn't that be one of the first things mentioned? Far as I can tell, he's a nobody that writes a blog. I can't find any references to any important pieces of software he's worked on that makes me think I should give a shit what he thinks. Moreover, the ideas he's propagating are bullshit, what he says is true if you don't write software, don't work on important software, and don't play on teams, otherwise it's just stupidity and he's showing his youth. Nothing to see here, move on.

      Taco, Hemos, Slashdot, et al.., remember way back in the day when we were infested by all those Katz articles and so they implemented the Katz-block technology to let us remove that crap from the front page? I like the developers section but this is a bullshit article, we need to introduce a more fine grained Katz-block. We need an "everything you know is wrong" subsection, a "new language or some shit like that" subsection, and a "technology x is dead" subsection so I can block that crap out of the front page.

    • Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented.

      From my decades of software experience across several different languages, there is no such clarity.

      Comments are useful, but code is often clear enough by itself. And bad (out of date) comments are absolutely worse than no comments at all as a coder will often trust the comments first.

      So while some code should be commented, not all code should be. And that's not really

    •     I actually did one of those comments a few days ago. There wasn't a better way to do a particular piece of code, so I put the comment in "// This is ugly, but there isn't a better way to do it.". It's a note to myself and future developers not to bother trying to fix an insignificant ugly piece.

          I do agree with the article, not everything needs to be commented. He misses out on "self commenting" where the code explains itself, so you don't need to explain it in an added comment. Intuitive variable names rather than $a $b $c are very helpful both in development, and for future maintaining.

          Sometimes things are overcommented, like the default Apache httpd.conf. I've been known to clean up such files with "mv filename filename.orig | cat filename.orig | grep -v ^# > filename", just to shorten it down to something reasonable that can be read. If you're familiar with the Apache httpd.conf, there's no need for all those comments. But, if someone needs to reference them, they're in the httpd.conf.orig.

      • by cloudmaster (10662) on Saturday January 02, 2010 @01:05PM (#30623530) Homepage Journal

        To demonstrate why other people might be able to solve a problem you've been stumped by, lets look at the "mv | cat | grep" you provided. :)

        First, that doesn't check the return value of the mv, so if the mv fails, you'll just clobber the original file. And, piping mv is just dirty. The Borne shells provide && for that:

        mv && cat | grep

        So, we have a check that the mv worked before clobbering the original now. This is a good start. But, that removes the original and recreates it - so you're probably mangling the permissions. If you do a cp, you have two gains - you preserve the original permissions of the file, and you guarantee that there will be enough space for the new file (since it'll be smaller or the same size without any comments). So, now we have

        cp && cat | grep

        Finally, the "cat | grep" construct bugs me. Grep takes filenames as arguments; it doesn't have to read stdin. So the cat and pipe is spawning a new process and setting up extra file descriptors which are superfluous. The performance difference is negligible on a one-liner, but if this same construct is used in a tight loop, it adds up. It's basically a bad habit. Just use grep. :) So, ultimately, we have an optimised version which is notably more robust and faster and less to type:

        cp src src.orig && grep -v "^#" src.orig > src

        But wait, there's more! If you're using bash or ksh93, you can use shell word expansion to reduce the chance of typos:

        cp src{,.orig} && grep -v "^#" $_ > src

        And then, say you're sick of all this junk and just want to do it with one command that's shell-independent. Well, lets use perl:

        perl -i.orig -lne 'print unless /^#/' src

        So anyway, don't assume that someone else can't solve a problem more elegantly than you.

        And don't take this post too seriously. ;)

  • No Comment (Score:5, Funny)

    by Anonymous Coward on Friday January 01, 2010 @06:31PM (#30616700)

    No Comment

  • by Xaroth (67516) on Friday January 01, 2010 @06:33PM (#30616716) Homepage

    Clean code tells you how, good comments tell you why.

    Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.

    • Re: (Score:2, Insightful)

      by Brian Feldman (350)

      Clean code tells you how, good comments tell you why.

      Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.

      You seem to be implying here that good comments cannot explain how something non-obvious works. Often in software there are tricky sections of code that benefit from both comments explaining why a given algorithm is implemented but also how the control flow works. Comments are also extremely useful to mark spots that need attention later but are sufficient for now, and also to document any type of "contract" that a particular body of code adheres to.

      • by Nerdfest (867930)
        In most high level languages, description method or function names tell you why as well.
        • Re: (Score:3, Insightful)

          by dkf (304284)

          In most high level languages, description method or function names tell you why as well.

          Function (and argument) names don't tell you the why of the function. They tell you why you would call the function. That's an important difference. (For example, a function might be called GenerateUniformRandomNumber(int from, int to), but that does not say anything about the particular algorithm used to do the generation, which might need a few references to the literature on PRNGs to do properly.) If the code has description metadata attached to it then that's quite possibly containing a lot of what is c

    • by Wraithlyn (133796) on Friday January 01, 2010 @07:00PM (#30616896)

      Indeed, and perhaps it's an obvious point but I'd also add that clean code should also tell you "what".

      Whenever I have a block of code whose purpose seems unclear, I try to put it into a function whose name clearly describes what it does. This immediately makes it more understandable, and reusable to boot.

      Comments should explain why something is done the way it is, the reasoning behind it. They should not simply label what something IS, that should be the job of good naming practices.

    • by BikeHelmet (1437881) on Friday January 01, 2010 @07:42PM (#30617216) Journal

      I don't clutter my code with comments. If there's a comment, it's a really important gotcha, or something that doesn't make sense but has to be left for legacy reasons.

      And I write a detailed description at the top of every file. Not just what a class does, but also why. Why some of the methods do what they do, and other places they might get used that might need to be changed.

      Nothing annoys me more than...

      /* Method name: Foo
      Returns: int Bar
      */
      public int Foo()
      {
      return Bar;
      }

      When a comment could be run through a preprocessor to turn it into the actual code, the comment is saying too much, and should be removed, simplified, or changed.

    • Re: (Score:3, Informative)

      by b4dc0d3r (1268512)

      To supplement my comment elsewhere, what you're suggesting can be more easily documented in a tech design type of document, not inline. It's easier to find that way, and you can include pretty pictures too.

  • Remember what is crystal clear to you may not be to the guy coming in to clean your mess up in a few years. ( or even yourself as you have learned more and advanced your skills, and have to go back, often with a 'wtf was i doing'.. )

    Having to decode your thought processes places extra a burden on the 'next generation'

    • by fdrebin (846000) on Friday January 01, 2010 @06:39PM (#30616744)

      Remember what is crystal clear to you may not be to the guy coming in to clean your mess up in a few years. ( or even yourself as you have learned more and advanced your skills, and have to go back, often with a 'wtf was i doing'.. )

      I worked on the same system for 15 years. More than once I saw some code and said "what idiot wrote this!?" ... only to realize it was me, 5 years ago. Yes, that did indeed lead to me becoming a) much less prone to "clever tricks" and b) much much better at explaining what (WHY) I was doing whatever it was.

    • Re: (Score:2, Insightful)

      by jocabergs (1688456)
      I think over documentation isn't on the whole a bad thing, but there have been a few times where I've been more confused by the comments than the code. I don't care if people get clever with code and have clear comments, but I hate when people try to have clever comments, comments are not supposed to be hard to understand.
  • by smartin (942) on Friday January 01, 2010 @06:35PM (#30616728)

    Having worked as a programmer for many years, all I can say is poorly commented and undocumented code is unprofessional and I would rather
    rewrite it than try to decipher it. I've heard all of these excuses before and all I can say to the people that make them is: Your code is not as
    good as you think it is.

    • Re: (Score:2, Informative)

      by MichaelSmith (789609)

      I would rather
      rewrite it than try to decipher it.

      In the environment I work somebody will try to import your change later and they will want to know why you made that change. They aren't going to be very impressed if your answer is that you couldn't understand the original code. By making that change you would be creating work for a lot of other people down the chain.

    • by CAIMLAS (41445) on Friday January 01, 2010 @06:49PM (#30616810) Homepage

      What bothers me is not so much undocumented code, but undocumented functions and/or blocks of code. Main should be well documented, and a function should have a line or two explaining its function, but unless its particularly obtuse code, I don't want/need documentation.

    • by TheRaven64 (641858) on Friday January 01, 2010 @06:52PM (#30616832) Journal

      Your code is not as good as you think it is

      Even if it is, the person reading it might not be as good a developer as you, or may be as good (or better) but with different experiences. In both cases, they may not be able to read and understand your good code without comments. When they change it and it breaks as a result, then it's your fault.

    • by tomhath (637240) on Friday January 01, 2010 @06:53PM (#30616846)

      Wrong on all accounts

      RTFA, the article starts out with these two sentences:

      It seems to me getting good at writing comments is an under-appreciated part of a Programmer's development. However, I feel that this is a part of programming that's almost as important as writing code itself.

      His point is that worthless comments are worse than no comments at all. Unfortunately a large percentage of the comments you see in code today were autogenerated by the IDE and are just noise.

    • Re: (Score:3, Interesting)

      by SerpentMage (13390)

      And therein lies the problem.

      There are two major problems:

      1) As much as I would like to say that documentation helps, I actually don't think it helps unless you writing an API. But even then I wonder. The real problem with documentation is that as much as we would like to keep it up to date, it does not happen. I personally would prefer modular code that works without tricks than code with comments and tricks.

      2) The problem with comments is that it fails the psychological test. When I write something down

      • Re: (Score:3, Insightful)

        by jbolden (176878)

        The next programmer in line may not need to understand the complex multi threaded stuff at all. For example he may be revising the UI or the backend datastore. Reading your multi threaded comment may be effectively him just having a comment that the is no I/O and that the block is all CPU / memory; and that is good enough.

    • Re: (Score:3, Insightful)

      by Nerdfest (867930)
      You shouldn't need to decipher the code. Most of the problem is not the missing documentation, but the poorly written code.
    • by 0xdeadbeef (28836) on Friday January 01, 2010 @09:12PM (#30618032) Homepage Journal

      If you have to "decipher" code, it is wasn't good to begin with. I used to believe the comment religion, it was beat into us in school, but once I started working with people with similar or greater skill than mine, I noticed that comments became few and far between. Usually they are only necessary to explain the intersection with something external or poorly designed, such as an API call or hackish work-around. Comments are no substitute for not knowing the problem domain. If you need to educate a new hire, you should already have documentation that explains the architecture.

      If you want to talk unprofessional, the absolute worst are comments that state the obvious. It's like watching a movie with an imbecile talking to the screen, telling himself everything that is happening. It goes without saying that those comments are usually uncapitalized, lacking punctuation, and full of misspellings.

  • by Greg Hullender (621024) on Friday January 01, 2010 @06:42PM (#30616762) Homepage Journal
    In thirty years of programming, I've heard one person after another argue about how to comment and how much to comment, but what I've never seen is any kind of serious study attempting to measure what actually works best. I personally like to make comments paragraphs, not lines, and generally end up with code that's 1/3 to 1/2 comment lines, but the most I can claim is "it works for me."

    I do think good commenting has to be a key part of software engineering (when it finally becomes a real engineering discipline), and I know software engineering is a hot topic these days, so perhaps there's a paper on this that I just haven't seen yet. If not, someone really ought to do a serious study. And then start teaching people something that's actually known to work.

    --Greg

    • by tomhath (637240) on Friday January 01, 2010 @07:08PM (#30616962)

      A former employer (a very big multinational corporation) did a study that tried to correlate the number of comments in code to the number of problem reports against it. Not surprising to me, they found that in general the more comments in the code, the more problems were reported against it. That was my observation as well; bad programmers couldn't figure out a straightforward solution to a problem so they wrote messy code with lots of comments trying to explain what they were doing. The really good programmers wrote simple clean code that only needed a few comments.

      Another characteristic of bad programmers that I noticed was their tendency to keep copying data from one data structure to another instead of using it in place. Obviously an indication of bad design, and it introduced lots of bugs. You knew as soon as you opened a source file and saw comments like "Copy blah-blah data from abc array to xyz array" that you were in trouble.

      • Or (Score:4, Insightful)

        by MichaelSmith (789609) on Friday January 01, 2010 @07:31PM (#30617116) Homepage Journal

        The code which is business critical and necessarily complex gets commented a lot as a mitigation measure. But it still has problems, often because the business requirements change a lot or are poorly defined.

      • Re: (Score:3, Funny)

        by jim_v2000 (818799)
        > they found that in general the more comments in the code, the more problems were reported against i

        The obvious solution then is to simply ban employees from using comments in code.
      • Re: (Score:3, Interesting)

        by digitig (1056110)

        A former employer (a very big multinational corporation) did a study that tried to correlate the number of comments in code to the number of problem reports against it.

        Which seems to me to be representative of the sort of blunder very big multinational corporations seem particularly prone to. Just count the comments, never mind what the comment says. /* Stable sort in place, efficiency O(n log n) */ counts for the same as /* Oblig comment coz a dude in QA sez I has to */

  • by nmb3000 (741169) <nmb3000@that-google-mail-site.com> on Friday January 01, 2010 @06:42PM (#30616770) Homepage Journal

    I disagree with this general statement:

    For instance, would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments? In most cases, code's readability suffers more when it's overly verbose than when it has a high comment to code ratio. Thus, I would choose to write the comment in most cases.

    First, I think any time you consider writing some clever one-liner in real production code you should rethink long and hard. Is the hypothetical 6 fewer lines of code really worth it? Unless you're doing it for absolutely required performance reasons, the 6 lines of code you save won't buy you anything but the wrath of whoever has to come along in 3 years and refactor your code.

    Of course you can be too verbose, but it's a much rarer problem than the alternative. Even overly verbose code is usually easier to understand, easier to maintain, and easier to refactor than that clever little one-liner. And if you're that worried about a verbose section of code, extract a method, give it a good name, and be done. Now you have both a one-liner method call that is easy to read in context and a more verbose implementation that is easier to understand and maintain in the future.

    • And if you're that worried about a verbose section of code, extract a method, give it a good name, and be done.

      In total agreement here. Usually just look at a short-ish method's name, its parameters, and its return value, makes it clear what it does. This is different than if that same code were included in-place, since in that situation its not clear what the "inputs" and "outputs". Plus extracting it usually makes the section from which it was extracted easier to read.

    • by Anonymous Coward

      Early COBOL and Fortran computation code proves you wrong here. COBOL, without COMPUTE, required a separate line for each operation. Fortran from the start showed simple algebraic equations.

      COBOL
      ======
      MULTIPLY B BY B GIVING B-SQUARED.
      MULTIPLY A BY C GIVING A-C.
      MULTIPLY A-C BY 4 GIVING A-C-4.
      MULTIPLY A BY 2 GIVING A-2.
      SUBTRACT A-C-4 FROM B-SQUARED GIVING DISCR.
      CALL SQRT USING DISCR GIVING RT-DISCR.
      SUBTRACT B FROM RT-DISCR.
      DIVIDE RT-DISCR BY A-2 GIVING ROOT-1.

      Fortran
      =====
      R1 = (-B + SQRT(B**2 - 4*A*C))/(2*A)

      Do

      • by Ragzouken (943900) on Friday January 01, 2010 @07:49PM (#30617278)

        Your example misses the point precisely because it's just as clear in one line than in eight. You obviously shouldn't break up everything into as many lines as possible.

      • Re: (Score:3, Insightful)

        by zippthorne (748122)

        Either way you need commments. Your example code only finds one root, and doesn't handle the case of positive b and abs(ac/b^2) 1 very well. Your comments could explain why you don't expect that case to arise, and why you only need one root.

  • In other news... (Score:5, Insightful)

    by CAIMLAS (41445) on Friday January 01, 2010 @06:43PM (#30616776) Homepage

    In other news, people have personal preferences, just as they do in the literary world. Some people like Ayn Rand, others hate her. Some like Stephen King, others hate him. Not so much their stories, but their writing styles.

    Snowcrash is an awesome story; one many can appreciate, but most people couldn't get through his writing style to finish the book.

    I think that if more people wrote code (or, for that matter, books) like George Orwell wrote his books, code (and books) would be generally more readable: shorter sentences (lines of code) which convey a single meaning (function), strung together into short paragraphs (code blocks), chained together into a larger cohesive whole.

    • sentences linked into a meaning into a paragraph into a story! Brilliant!

      Actually, I really like this post. Someone, please mod this up.

      If more people wrote simpler code, it would be easier to read on my end, as a non-programmer

  • I had excessive commenting drilled into me in college. It's one of the things I've had to unlearn.

  • Please no (Score:5, Insightful)

    by dachshund (300733) on Friday January 01, 2010 @06:52PM (#30616836)

    Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting". This is particularly important when you're working with anything other than standard libraries --- you might know what "libfzp_inc_param_count_fast", but your reader probably won't.

    Right now I'm working on a crypto library that incorporates a lot of very specific elliptic curve operations. My technique is to comment the hell out of every damned interesting piece of code on the assumption that a picky reader can turn off the damned comments if they get in his way. In fact, there are various places where I've actually scaffolded all of the comments before writing a line of code. Doing otherwise would have been an enormous headache and made bugs a whole lot more likely. And this way even a non-expert should be able to understand the entire program flow.

    Unfortunately, one of the previous pieces of software in this area followed the poster's "self documenting code" style (very nice, clean, well written code with no comments), and even I find it difficult to piece together what's going on in places --- not because all of the code is crypto-specific, but because the author has thrown so much effort into writing "clean, pretty" code that it's actually hard to know where the crucial pieces are. I can't quite explain why I find this so irritating, but perhaps some of you will know what I mean.

    • Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting".

      Yeah there is this guy I have the misfortune to be working with. Once in a code review he insisted that all my code be double spaced (one blank line between every line) because he was having trouble reading it. I said why don't you configure your editor accordingly. He said in his team they do pair programming so every workstation has to be set up exactly the same way...

    • Unfortunately, one of the previous pieces of software in this area followed the poster's "self documenting code" style (very nice, clean, well written code with no comments), and even I find it difficult to piece together what's going on in places --- not because all of the code is crypto-specific, but because the author has thrown so much effort into writing "clean, pretty" code that it's actually hard to know where the crucial pieces are. I can't quite explain why I find this so irritating, but perhaps so

  • Comments are useful if kept up to date with the code. Otherwise they turn into bald faced lies or wishful thinking.

    Code that follows a logical structure, proper use of white-space, well-name variables and methods, etc is far easier to read and debug than code that has a lot of comments. Comments are non-standard and difficult to search for when looking for a problem.

    Comments are best reserved for things which are non-trivial to figure out by reading and following the code.

  • Choice of Language (Score:3, Insightful)

    by mandelbr0t (1015855) on Friday January 01, 2010 @06:54PM (#30616856) Journal

    It really depends on what language you write your code in. Object-oriented languages in general require less documentation since good design and properly named methods and properties do document things relatively well. Class-level documentation is much more important than documenting the details of the methods themselves. Java and .NET require much less documentation to maintain. I've looked over Java code I wrote years ago, and it still makes perfect sense, even though I've only really documented the API and not the details. Perl and C code, on the other hand, can be unmaintainable even with a number of comments, because the old functional design is not easily maintainable. Consider rewriting these in a more modern language.

    Call me a hotshot if you want, but I shouldn't have to assume that the person maintaining my code is a moron, nor that my non-technical manager needs to understand every single statement I wrote. I play nice with QA, and happily write test cases for my code. That's as far as I'm willing to go to ensure that my code quality is good, and that I can leave without the possibility of my code degenerating into the spaghetti-like mess I've had to clean up on a number of occasions. Sure, I don't get hired to write code anymore, but I don't care. Software Engineering and overdocumenting every single tiny intranet project is wasteful. Cleaning up after morons who believe that their engineering background can make up for their lack of talent and experience is aggravating. Answering to them is intolerable. There's other things I can do with my technical background that don't involve butting heads with people who dogmatically apply software engineering methodology to everything they do. It's their loss, not mine.

    • by Nerdfest (867930)
      Exactly. If you're coding in Assembly, you damn well better comment, but if you're coding in Java, I'd better not need much, if any. Generally, any high level language code in need of a lot of comments should never make it through code review.
  • I suspect comments in code are like project notes.

    Even when I come back to my own projects a year or so later, it is obvious what I was doing with x widget attached just so the y widget.

    It is rarely obvious WHY I came around to that solution.

    Project notes, and I suspect good comments in code, address the though processes behind doing something this way, rather than explaining in detail WHAT the code does.

    10 REM FOR 16 BIT NMS MACHINES
    20 FOR X=1 TO 10
    30 PRINT "HELLO"
    40 NEXT X

    (told you I wasn't a coder)

    But li

  • by EsJay (879629) on Friday January 01, 2010 @06:56PM (#30616868)

    When you update the code that the comment references, you usually have to update the comment as well.

    If your comments are that detailed, you're doing it wrong.

    • Re: (Score:3, Interesting)

      Except that a programmer should be able to use (call) your api / public methods without having to read their
      implementation. The method signature and comments should be enough.

      Therefore, as well as conveying the gist of what the thing/method is and how it fits into its context,
      you should also document all significant corner cases or unexpected behaviours of your object/method.

      And if you change the implementation in such a way that you falsify one of those comments, without
      modifying the comment, thats a fail,

  • by anti-NAT (709310) on Friday January 01, 2010 @06:57PM (#30616872) Homepage

    No offence intended to him, but he's just re-interating the sort of commentary on commenting that's in Code Complete, The Practice of Programming, Linux kernel CodingStyle etc. He's not offering any original insights, or telling war stories that people can learn from. Any decent programmer would already know these myths, and if they didn't, they really should be reading books such as the ones I've listed, not a blog entry with very little original content.

    IOW, what makes special enough to be Slashdot front page news?

  • ...would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments...

    Depends on the efficiency and maintainability. A one-liner that's "perfect" is probably worth the extra comments. Ten lines of self-evident code may not be better. Personally, I can't stand code that starts "boolean done = false; while (!done) {...}" when the condition can be determined inline using an operational variable.

  • by lax-goalie (730970) on Friday January 01, 2010 @07:03PM (#30616920)

    would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?

    Easy. 10 lines, no comments. After writing a couple of million lines of code, the more code I write, the more I unwind it. Somewhere along the line, adolescent programmers got the idea that jamming all your logic into as few unreadable lines as possible is the fastest way to manliness. Way, way wrong.

    Modern compilers and interpreters do a pretty good job nowadays. Source code bytes are near free. If you have to skull out dense code 6 months after you've written it, you're doing something wrong.

    (OK, Lisp and APL are special cases, but really, when's the last time you wrote Lisp or APL, other than for fun?)

  • by caywen (942955) on Friday January 01, 2010 @07:05PM (#30616932)

    Every line should be commented, like: // Declare function called doit with one int param that returns an int
    int doit(int i) // See above comment
    { // The function's open brace. I like to put braces on their own line. You should too!! BTW, this is C code, so braces are totally the way to go.
          if(i == 0) // Check if i is 0. You know, in C, "==" is the way to compare values, unlike in VB where you use a single "=". Just thought u should know.
                return 0; // Return 0. That is, all the bits of the return value are 0. We could also return i, because i is 0, too. That is, all the bits of i are 0. On a 32 bit system, there would be, like, 32 0's.
          else
          { // Begin an if block using a brace (this is C syntax!!!)
                int j = i - 1; // Declare an int variable named j that is one less than i
                return i + doit(j); // Return the sum of i and the value of calling doit with j
          } // Finish the if block with a C close brace. By the way, we could have written the above code as return i + doit(i - 1) without using the braces.
    } // The function's close brace.

    There! Now that is both way readable and informative. Anything less would just not pass my code review.

  • by presidenteloco (659168) on Friday January 01, 2010 @07:05PM (#30616936)

    If you don't header-comment your class or public method,
    I have to conclude that you cannot articulate what it is or what it
    means or is for. So probably the code is incoherent/inconsistent too.

    So that's going to make me write my own instead of using your code.

    Or maybe you can articulate what it is about but are borderline
    autistic and don't see the need to communicate meaning to others.
    To me this just means you are so inexperienced in programming that
    you a) don't understand the costs of maintenance, and
    b) don't even realize that you yourself aren't going to be able to figure
    out your code in six months.
    Either way, I'm not using that code if I can help it.

  • myths about excessive code comments. Provide comments in places where the comment might be useful. If you have some obscure function, the purpose of which might be confusing if you or someone else looks at it a year later, then you need a comment. The more obscure or terse, the more detailed the comment should be. On the other hand, if the function's purpose is obvious just by glancing at it, or the function name is sufficient to describe the entire purpose of the function, there's probably not a need f

  • There are just 3 good reasons for comments in code: (a) to refer to a published paper describing an (obscure) algorithm, eg '[fast graph traversal algorithm, M. M. Balakrishnarajan and P. Venuvanalingam ,Computers & Chemistry, Volume 19, Issue 2, June 1995, Pages 101-106] , (b) to indicate an arcane, obscure usage, which would be better eliminated, but sometimes cannot be eg in device drivers, when merely addressing a device register has side effects, (c) to very briefly document major parts of program
    • by petes_PoV (912422) on Friday January 01, 2010 @07:55PM (#30617314)
      You presume that the person coming after you will have both your background and your programming ability. This is incorrect. No-one who sees your code will have the same background you have and therefore they will not have the same writing style or familiarity with the problem you were trying to solve. Comments are primarily (but see later) there to save time. They act like signposts on the roadside and should guide people towards an understanding of what a section of code does, why it does it and how it relates to the stuff around it. If your comments don't do this, then you're not a very good programmer. Just like you can drive around and will eventually (as the earth is round) wind up at your destination, having a map, signage and/or a GPS makes getting to the right place a whole lot quicker. Your comments should do the same.

      While you are right (as all *experienced* programmers know, anyway) that /* increment the counter */ comments are pointless (but harmless) you've missed an extremely significant type of comments. These are the warning to future programmers why you DIDN'T use the obvious approach, or why a particular algorithm is not suitable for the task in question. Further, code that has been corrected, modified or had bugs fixed MUST have comments to identify that fact. These comments are at least as valuable as the actual code. Again, experience will teach you this.

      Finally, never, ever forget the most important rule of commenting. NEVER include a URL in a comment. They change over time and cannot be relied upon to still exist in 3 months, let alone the lifetime of a software product. A similar warning should exist for book / magazine references, too. Not only do they become unobtainable or go out of print, they also get modified or corrected in the "second edition" and therefore still can't be relied on. If an algorithm has a well known name, such as Bresenham's, then by all means quote that otherwise, explain the algorithm in, or before the code that implements it. Unless you want the next guy to curse your name - provided you put that in the comments.

  • by DaveGod (703167) on Friday January 01, 2010 @07:34PM (#30617158)

    Working in accountancy (and doubly-so for audit) a well-commented file is absolutely necessary. Like (I suspect) computer code, the file should stand on it's own - a competent fellow professional should be able to fully understand it and be comfortable reaching the same conclusions. This is not only good practice for the benefit of your firm but a professional requirement: my institute comes along every few years, selects a few files and basically if they have difficulty understanding the file (or worse, reached different conclusions) then you're in a lot of trouble.

    Many of the points in TFA hold up well however - explaining things unnecessarily merely adds bloat, irritates and wastes the time of the reader by telling them obvious, patronising or pointless things. And yes, a perfect accounts job doesn't require any explanation because the schedules will be self-explanatory.

    The thing is though, if you're doing anything complex (earning your salary), have to make corrections (hackjobs) or judgements then you need explanations. Manager's will be reviewing your work and you or a colleague will be referring to it next year. If explanations go out of date, update them - if they had value before then value is there in updating them. Yes there is a cost, so there is a tradeoff vs their value to the file. The key is competent fellow professional. Assume your colleague will be reviewing your work and be satisfied that they will be able to understand and appreciate it.

    If you're just churning out "stuff that works" then you're at best a technician.

  • The flipside (Score:3, Interesting)

    by BigBadBus (653823) on Friday January 01, 2010 @07:38PM (#30617190) Homepage
    I used to work for a company [paullee.com] that didn't believe in commenting code...took ages to reverse engineer the code...
  • Experience (Score:3, Interesting)

    by GrahamCox (741991) on Friday January 01, 2010 @07:50PM (#30617282) Homepage
    Experience shows how much you need to comment and what the comments worth writing consist of, just as experience tells you how to structure the code in the first place. "Rules" about commenting are perhaps useful starting points for the inexperienced, but with experience you can write your own rules.
  • by tengwar (600847) <slashdot AT vetinari DOT org> on Friday January 01, 2010 @08:03PM (#30617380)
    My favourite bit of code was about 22 years ago. It was supposed to control some scientific equipment that we had bought from Denmark, and I had insisted on getting the source because of previous problems with the supplier. In summary:

    - 6000 lines of Pascal
    - 200 global variables
    - 3 local variables
    - 1 comment - the single word "midlertidig"

    Oh, and one bug. Code really was less buggy back then.

    Now get off my lawn, you kids.

  • by upuv (1201447) on Friday January 01, 2010 @09:58PM (#30618506) Journal

    Because his opinion is against a fairly standard convention he declares himself right and the opposite opinion to be myth.

    How arrogant can you get. Really.

    "I think MS Windows sucks Donkey Nuggets. Therefore everyone should switch to Android. The power I wield is frightening."

    I've been writing code for over 20 years. One thing you learn is that you don't want those "Hey how do you do xyz with method ABC in the code you wrote 10 years ago." calls. How do you avoid this your code follows you like a bad poo cling on. YOU COMMENT YOUR CODE. With descriptions, examples, purpose and anything else that is relevant. You probably should spend as much if not more time on the comments than the code. Cause it will save you heaps of time in the future.

    As for documentation that is external to the code? Well it's useless. Because repositories change move and mutate. Over the years the design/requirements/arch docs all seem to vanish. The only thing that seems to live on is the actual code. Why. The code is the business not the power point slide show. The code therefore should also be the documentation.

    So Mr. I'm 20something and know everything about writing code. Time to join the real world. I for one never want to have to fix your code.

Chemist who falls in acid is absorbed in work.

Working...