Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!

 


Forgot your password?
Close
typodupeerror
×
Programming IT Technology

How to Write Comments 556

Posted by CmdrTaco from the no-not-the-slashdot-kind dept.
Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See " Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.
This discussion has been archived. No new comments can be posted.

How to Write Comments More

How to Write Comments

Comments Filter:

  • Reading (Score:5, Funny)

    by Southpaw018 ( 793465 ) * on Wednesday November 30, 2005 @11:55AM (#14147378) Journal
    Code should read easy Like many Slashdot comments See? It's not so hard.

    • Re:Reading (Score:5, Funny)

      by Southpaw018 ( 793465 ) * on Wednesday November 30, 2005 @11:57AM (#14147403) Journal
      *grumble* Forgot the <br>s.

      Code should read easy
      Like many Slashdot comments
      See? It's not so hard.

    • Re:Reading (Score:3, Interesting)

      by jmony ( 245233 )
      Problem with Slashdot comments is like code comments... too few is bad, too much is bad. // This line outputs the result

      How many times can we see a line like this... that's just writing comments without any reason.

      I prefer function header comments which describe what the piece of code as whole does. Not everyline, as teachers say it should be done.

      • Re:Reading (Score:5, Informative)

        by InvalidError ( 771317 ) on Wednesday November 30, 2005 @01:01PM (#14148065)
        Same for me.

        Having one-liner comments all over the place makes comment maintenance more troublesome and can distract from actual comprehension of what is going on while reading the code, particularly when there are bits of orphaned antique leftover comments. A single comment blob before a function or large code sections tells the reader about the spirit of code to come without interfering with reading beyond there and makes it easier to maintain comment coherence when changes are made.

        For more convoluted code, I often add blobs before major loop/switch/etc. too - adding comments while I write these things takes less time than what it may take me to re-read the code until I remember exactly what it does and how. (inputs, outputs, side-effects, etc.)

        • Re:Reading (Score:5, Insightful)

          by IngramJames ( 205147 ) on Wednesday November 30, 2005 @01:16PM (#14148221)
          an distract from actual comprehension of what is going on while reading the code, particularly when there are bits of orphaned antique leftover comments

          I know this is a religous topic, but I personally would say that old, left-over comments are simply bad practice. Well-maintained comments and well maintained code are the ideal solution. I don't think there's any excuse for not updating a comment which is right there, in the code you're about to change.

          I've suffered from antique comments, and also no comments; IMHO, they are both as bad.

          Feel free to flame me now :)

        • Re:Reading (Score:3, Funny)

          by Sax Maniac ( 88550 )
          I hate one-liners. Here's a fake example of stuff I see all the time:

          if (foo) { /* OHO! */
          if (bar) return; /* Well, well, false alarm. */
          if (!x) /* Class is bogus. */
          z=y; /* Did we already have one? */
          }

          Great, I'm sure this Howard-Cosell running commentary is cute if you already know what the code is doing, but it means nothing to everyone else. Comments are not for you, they are for other people.

          • I am an old school coder, and I see a lot of this stuff these days:

            if (foo) {
            // Bleah
            // Bleah
            // Bleah
            // Bleah
            }


            Why do people put the opening bracket on the same line as the conditional? where the hell did this come from? I see it a lot in JS, and more modern C/C++ code. I always though you were supposed to use carrage returns and tabs to make it easy to see the body of a conditional:
            (underscores for whitespace; damn you slashcode!)

            if (foo)
            {
            _____ // Bleah
            _____ // Bleah
            _____ // Bleah
            _
            • Believe it or not, one place it comes from is presentation slides (PowerPoint, or just plain overhead transparencies).
              It lets you get the whole example on the page in a font that is readable from the back of the lecture hall.

              Personally, I prefer it like this. The opening brace on the line with the conditional (for, while, if, etc), the conditional block indented, and the close-brace at the same indent as the start of the conditional. I tried a few other ways*, but didn't like them: they weren't readable e

            • > I am an old school coder
              > Why do people put the opening bracket on the same line as the conditional?

              You must not be very "old school" if you don't know the answer. The cuddled braces are the original K&R indentation style; they are what C was supposed to look like.

              Another answer is that there are two different ways to look for blocks. I look at indentation as a clue to the new block and when I see a brace on a line by itself I immediately interpret it as:

              if (x);
              {
              }

              This is especially true when I c
              • I started coding doing K&R C style braces. I have used them for many many years. I have recently been trying the opening brace on a separate line. It isn't so bad. There are a LOT of languages out there other than C. You can make a bunch of logical arguments for both ways. It is almost like vi vs. emacs. I can spot blocks either way. I also do a lot of Ruby coding which doesn't even use braces and instead uses the end statement to denote the end of the block. So you actualyl *have* to know what statemen
                • With 1280x1024 being a relatively common display resolution used by developers these days I don't think it is such a big deal to have an extra line for the braces


                  <disgruntled 1024x768 coder>
                  How big a deal it is depends a lot on the kind of code you're writing. If you've got lots of small ifs, tight loops, and small functions, the braces *do* take up a significant chunk of screen real estate.
                  </disgruntled 1024x768 coder>

      • Re:Reading (Score:3, Informative)

        by dcam ( 615646 )
        I'd largely agree with this.

        One helpful practice I picked up (see Code Complete, Steve McConnell) was to design functions in advance and use the design a the comments.

        eg
        function foo()
        {
         
        // open input file
         
        // parse into local variables
         
        // print result

        }
    • public void GNAAT()
      {
      System.IO.Stream stream = System.Net.HttpWebRequest.Create("http://www.goats e.cx/receiver.jpg").GetResponse().GetResponseStrea m();
      System.Drawing.Bitmap bmp = new System.Drawing.Bitmap(stream, false);
      stream.Close();
      System.Windows.Forms.Form form = new System.Windows.Forms.Form();

  • Comments (Score:5, Funny)

    by LiquidCoooled ( 634315 ) on Wednesday November 30, 2005 @11:56AM (#14147385) Homepage Journal
    <!-- Damn users clicking too quickly on article -->
    <!-- why don't they ever RTFA? -->
    <b>Nothing for you to see here. Please move along.</b>

  • Haiku Commenting? (Score:5, Informative)

    by drewzhrodague ( 606182 ) <drew@nOsPaM.zhrodague.net> on Wednesday November 30, 2005 @11:57AM (#14147394) Homepage Journal
    Actually, that would give some of us that have to review code something interesting to look at. Those that think code is self-commenting, forget that there are people like me, who aren't great programmers, who have to either fix your bugs, make simple modifications, or add really simple things. When there aren't comments, it is hard to figure out what parts of what do which.

    • Re:Haiku Commenting? (Score:4, Insightful)

      by mcvos ( 645701 ) on Wednesday November 30, 2005 @12:05PM (#14147489)

      When there aren't comments, it is hard to figure out what parts of what do which.

      What parts do what should be clear from the names of function calls and variables, but whenever a function becomes longer than something really short, yes, it needs comments describing what happens where. If a function does something complicated, it's worth starting with a comment describing pre- and post conditions.

      That said, before you add a comment, first check if you can make the various identifiers any clearer. And then still add the comment, unless it's suddenly become really stupid.

      • Re:Haiku Commenting? (Score:5, Informative)

        by Coryoth ( 254751 ) on Wednesday November 30, 2005 @12:31PM (#14147749) Homepage Journal
        What parts do what should be clear from the names of function calls and variables, but whenever a function becomes longer than something really short, yes, it needs comments describing what happens where. If a function does something complicated, it's worth starting with a comment describing pre- and post conditions.

        Now there is an excellent idea! It doesn't take a lot of effort - you should be able to come up with some basic constraints on inputs and outputs if you have any decent idea of what the function does - but it is very helpful documentation to anyone else, particularly for people who have to call the function (as it clerly delimits exactly what they need to provide, and exactly what they can expect to get back). Better yet, as long as you use a system that supports it you can get a whole lot of benefits in terms of automated checking and debugging of your code, saving you a lot of effort later.

        Eiffel [loria.fr] and D [digitalmars.com] support pre and post conditions directly in the code (instead of in comments). Java has JML [iastate.edu] which is a syntax for writing pre and post conditions in comments, as well as some tools to do extra checking, add runtime checks to your code (or not) based on the conditions, write the conditions into JavaDoc properly, and automatically generate JUnit tests based on the conditions. If you program in Ada there's SPARK [praxis-his.com] which supports pre and post conditions as comments as well as a range of other annotations, and provides extremely powerful tools to do extensive static checking and analysis and even generate automatically simplied proof obligations based on your annotations. If you program in Python there's PyContract [wayforward.net] which allows you to write pre and post conditions into docstrings and switch on or off runtime checking of those contracts. I expect there are plenty more, so hopefully other people can mention those.

        Jedidiah.

    • Re:Haiku Commenting? (Score:5, Insightful)

      by PsychicX ( 866028 ) on Wednesday November 30, 2005 @12:10PM (#14147534)
      Possibly the best advice I ever read/heard (I can't remember the origin), is to assume that the guy reading your code is perfectly familiar with the language. (Sadly this is usually inaccurate, but moving on.) So he can see what, mechanically, your code is doing. The idea of a comment is to explain how and why you are doing something. What is usually clear from the function name and accompanying documentation (be it doxygen/javadoc style or MSDN style or something else). I.e. if you have some jacked up mega-compound for-loop, a good comment explains why that loop is the way it is, and how it's achieving its goal (and possibly what precisely it's doing). A bad comment would be "this loop increments i, j, k, theta, and cheez_it until the cheez_it is failing to exceed the sum of i, j and the product of i, j, and k". That kind of information is right there in the code.

      In short, comments convey concepts and explanations, not mechanical descriptions.

      • Re:Haiku Commenting? (Score:5, Insightful)

        by Rorschach1 ( 174480 ) on Wednesday November 30, 2005 @12:22PM (#14147668) Homepage
        I'd suggest an exception to this for embedded code. When I'm writing something for a PC, sure, there's no excuse for not making the code readable. But when you're squeezing as much functionality as possible into a chip with maybe a couple hundred bytes of RAM and a few KB of flash, things get ugly.

        It's not uncommon for my code to do something really non-obvious to accomplish a task in a more efficient way. Processing sensor readings, for example - on a PC it'd be a simple floating point math operation. On the chips I use, the floating point library would itself fill the entire available memory. Instead, I wind up with a bit of hard-to-read code that accomplishes the same thing using the shift and multiply operations the CPU is good at. For my own sanity I leave very specific comments about what's going on and what the equivalent calculation is.

        • Re:Haiku Commenting? (Score:5, Funny)

          by p2sam ( 139950 ) on Wednesday November 30, 2005 @12:45PM (#14147902)
          The 1st rule of software engineering is: you do not put hacks in your projects
          The 2nd rule of software engineering is: you DO NOT put hacks your projects
          The 3rd rule of software engineering is: document you hacks
          The 4th rule of software engineering is: one hack at a time
          The 5th rule of software engineering is: if this is your first project, you'd have to do lots of hacks. :)
  • Asking Slashdot "Should I post comments?" is a bit like asking turkey's "Should we cancel Christmas?".

    Let the commencement of the comment posting beginulate!

  • cenqua! (Score:5, Funny)

    by i.r.id10t ( 595143 ) on Wednesday November 30, 2005 @11:57AM (#14147399)
    Simple, and I've posted this link a few times before, but you really need to use cenqua. Takes all the pain out of comments, and still allows personality quirks to show thru.

    The Commentator [cenqua.com]

    Just be careful on your settings and you should be fine.

  • Check out Rob Pike's thoughts on code commenting (Score:5, Informative)

    by podz ( 887481 ) on Wednesday November 30, 2005 @11:58AM (#14147415)
    Rob Pike, a former powergeek at ATT&T labs, and a present powergeek at Google, has the following [lysator.liu.se] to say about code commenting. In general, I agree with him.

    • Comment removed (Score:5, Insightful)

      by account_deleted ( 4530225 ) on Wednesday November 30, 2005 @12:11PM (#14147550)
      Comment removed based on user account deletion
    • "Procedure names should reflect what they do; function names should reflect what they return"

      This is one of the most effective methods of producing self-commenting code and I wish everyone writing programs would do this.

  • Good code is self documenting... (Score:5, Insightful)

    by Private Taco ( 808864 ) on Wednesday November 30, 2005 @11:59AM (#14147419)
    Just like good documents are self coding...
    • That is the trick, though. You put too many comments in your code, and you end up maintaining your comments as well. Or worse, you end up with code that obviously doesn't match the comment. Or even worse, you end up with code that doesn't match the comments, but not obviously -- sort of software counter-intelligence.
    • With well-commented code and a syntax-directed editor, I find it easier and quicker to read comments than reading the code. If I suspect there is a problem in the code, then I start to read it.

      The best way to code + comment is to write out the algorithm or steps of a function using comments, and then fill the code in. Good commenting is a bit of an art, and definitely takes a while to learn more through experience than instruction.

    • Re: Good code is self documenting... (Score:5, Interesting)

      by bunratty ( 545641 ) on Wednesday November 30, 2005 @12:22PM (#14147673)
      Yeah, right. I recently debugged some code that did matrix calculations. It turns out that the matrix involved was always positive definite, and therefore the calculation could be done by performing Cholesky decomposition rather than explicitly taking the inverse of the matrix. Needless to say, there were no comments explaining any of this, and it took me hours to reconstruct the thoughts and derivation behind the original code.

      Here's the original code:
      L = Cholesky(cov0);
      th1 = L.i() * th0;
      lrt = (th1.t() * th1).Trace();
      which is supposed to compute the same answer as the code:
      lrt = (th0.t() * cov0.i() * th0).as_scalar();

      I do agree that in general code should be self-documenting when possible, but sometimes you need a few lines of comments to explain a single line of code, or a few paragraphs of comments to explain a few lines of code. I added 17 lines of comments to that part of the program to explain 3 lines of code.

      • Some people say that when you see the need of a comment, see if you can fix the code first. In your example that would mean putting the tricy calculations in a separate function, that also has the benefit that if you find a better way to write it, you only have to make the change at one place even if the function is used in many places. Maybe you'd still want to add comment in the function to clarify it though considering the coplexity of the code. But in many cases just the name and the docstring of a func

      • Re: Good code is self documenting... (Score:5, Insightful)

        by 2short ( 466733 ) on Wednesday November 30, 2005 @05:49PM (#14150941)

        Self-documenting code is a wonderful thing, and greatly reduces the need for comments. Whenever someone brings this up, others say no, and eventually present an example such as yours: Entirely non-self-documenting. What the hell kind of variable names are those? L? a method named i()? Spell out "inverse" for gods sake! Of course you can't follow it. Hell, I know what Cholesky decomposition is, and I've read your explanation and I still don't know WTF that code is doing. I'll bet you needed 17 lines of comments. If you had instead changed the var names to something sufficiently descriptive, the code would successfully document what it is doing, leaving you to write a comment describing why; I suspect the third sentence of your post would have sufficed.
    • First of all you are implying that people write good code. Secondly you are making a mistake thinking that all code is easy to read when it is good. This is a lie.

      Obviously if you are writing some sort of a 3 tier application, which has a presentation, business and data tiers, then it is in fact possible to write good self documenting code, but you must also provide a design document, which explains how to read this code from high level point of view. But when you get into any specific details of that co

  • Comment every conditional branch or loop (Score:5, Funny)

    by Matt Ownby ( 158633 ) on Wednesday November 30, 2005 @11:59AM (#14147424) Homepage Journal
    I once read that a good comment will appear on every conditional branch or loop, and a good comment will also state the INTENTION for doing something, rather than what is actually being done (because the programmer can usually figure out what is being done). For example: // i starts at 1 instead of 0 because we don't want to process the application's name (first argument)
    for (int i = 1; i argc; i++)
    {
        printf("ARgument is %s\n", argv[i]);
    } // AND with 0xFF1234 because that is the first set of bytes in the file header
    if (u & 0xFF1234)
    {
        printf("File is valid.\n");
    } // say file not found instead of invalid due to reason blah blah blah ...
    else
    {
        printf("File not found.\n");
    }
    • // say file not found instead of invalid due to reason blah blah blah ...
      "blah blah blah" is mostly what I use for comments also :)

    • Re:Comment every conditional branch or loop (Score:5, Insightful)

      by MemeRot ( 80975 ) on Wednesday November 30, 2005 @12:13PM (#14147568) Homepage Journal
      Comments can be good,
      Avoid 'magic numbers' too,
      You've heard of constants?

      Seriously, this is not good code: if (u & 0xFF1234) - what the hell is u? Is it the start of the file? What if your file structure changes, you want to grep for every instance of 0xFF1234 and see if it needs to be changed? What if you changed your definition of what a good file is?

      Why not: if isValid(fileStart) - or if all you're doing is printing, just put it in the print statment? You do have to comment to explain why you're doing something, but the clearer the code is the easier it is to read and maintain.
      • Avoid 'magic numbers' too,
        You've heard of constants?

        Seriously, this is not good code: if (u & 0xFF1234) - what the hell is u?

        Exactly. I was thinking the same thing.

        Clearly labeled abstraction is self documenting and is just better.

        Instead of if (u & 0xFF1234), why not have a macro like #define VALID_HEADER(a) ((a) & 0xFF1234) and use if (VALID_HEADER(u)). u might be an OK variable, maybe not.

        One thing I do with perl code is instead of making a complex regexp that is expanded with inline commen

    • Re: Comment every conditional branch or loop (Score:5, Funny)

      by Black Parrot ( 19622 ) on Wednesday November 30, 2005 @12:45PM (#14147906)
      > I once read that a good comment will appear on every conditional branch or loop

      But be sure to put them outside the loop, so people won't have to read them over and over.
    • What a great example of lousty code and worse comments. How about the folowing... (Slashdot appears to offer a couple different ways to mis-format code; I've chosen incorrect indenting over comments can't start a line)

      // the only thing a comment here should explain is why you use & and not ==
      if (uFileHeader & VALID_FILE_HEADER)
      {
      printf("File shares at least one set bit with a valid file!\n");
      }
      else
      {
      // reason "blah, blah, blah", which I can not imagine existing,
      // certainly deserves

  • Dupe! (Score:2, Offtopic)

    by tpgp ( 48001 )
    Covered here [slashdot.org]

    Oh... you meant code comments... never mind!

  • Sure (Score:3, Funny)

    by Praetorian42 ( 248627 ) on Wednesday November 30, 2005 @12:00PM (#14147436) Homepage
    Sure my code is readable, but more often than not I find my comments explaining the screwed up business logic behind the code.

  • The why not the how (Score:5, Insightful)

    by Ckwop ( 707653 ) on Wednesday November 30, 2005 @12:00PM (#14147437) Homepage
    A comment should tell you why something is in place rather than what the code is doing:

    A trival example:

    Don't do this:

    public bool CheckSmsValue(Account smsAccount)
    {

    // Check tarriff is null
    if (Account.Tarrif == null)
              return;
    ...
    }

    Do do this:

    public bool CheckSmsValue(Account smsAccount)
    {

    // 30-11-2005 Fixes a null reference exception that occurs later on if no reference is available.
    if (Account.Tarrif == null)
              return;
    ...
    }

    Simon.
    • // 30-11-2005 16:08 GMT Fixes a type checking error when no value is returned
      if (Account.Tarrif == null)
                          return false;

    • Re:The why not the how (Score:4, Insightful)

      by Malc ( 1751 ) on Wednesday November 30, 2005 @12:29PM (#14147736)
      Person pet peeve here: dates and names/initials on comments. That's what source control is for, so don't litter the code with them.

      What I see here isn't preventing an exception, but rather checking the validity of a paremeter. I know it adds extra processing, but so many problems could be avoided if programmers put more effort in to input (e.g. parameter) validity checks. If it's an unusual situation, check for it in an assert as part of the pre-conditions at the beginning of the function (programming by contract). I'm assuming this is Java code in your example - does it not support assert now?

    • Re:The why not the how (Score:5, Funny)

      by op12 ( 830015 ) on Wednesday November 30, 2005 @12:29PM (#14147742) Homepage
      What about doing this?

      /* makes it public */ public /* boolean value */ bool /* function name */ CheckSmsValue( /* function parameters */Account smsAccount)
      /* start function */{
      /* Comment */
      // Check tarriff is null
      /* if statement */
      if ( /* variable */ Account.Tarrif /* equals */ == /* Null */ null)
      /* return */ return;
      /* dot, dot, dot */ ...
      /* end function */}

    • Re:The why not the how (Score:5, Informative)

      by rjstanford ( 69735 ) on Wednesday November 30, 2005 @12:39PM (#14147837) Homepage Journal
      Sorry, but you happened to hit on one of my pet-peeves with non-self-descriptive code. I do agree with your suggestions, mind you, but I see it all the time: functions describing how they work, not what they do. Sorry to pick on you, but in this case why not take:

      public bool CheckSmsValue(Account smsAccount)
      {

      And instead say:

      public bool isSmsValueAccurate(Account smsAccount)
      {

      That way, anyone who glances at the call will know what the function does. In fact, the first one could be checking for existance, non-existance, accuracy, threshold, who knows? Heck, its exactly the kind of function that I could see being called in many different places by people expecting it to be checking different things. Or coder1 adds it in expecting it to check for "positive" as well as whatever else, months later coder2 realizes that it doesn't and adds the "extra check" into it - its a check function, after all, right? And then coder3's code in some far-away place suddenly starts failing because he didn't want that check in the function.

      A good name should be an implict contract. The function above should, by that definition, return "true" if it did at least "check" the SmsValue, and "false" if it didn't bother to... not quite what the original intent was. Probably.

      Phew. Sorry for the long-windedness.

  • Words to live by (Score:5, Funny)

    by 3CRanch ( 804861 ) on Wednesday November 30, 2005 @12:01PM (#14147447)
    During college I always lived by:

    "It was hard to write; it should be hard to read"

    'course the profs didn't appreciate that much...
  • You should use Java instead (or another easily readable and understandable programming language). Ok there may be some cases where a comment is needed but it is quite rare. Give the source, that should be enough. Of course, if your design is complex, you should write design/technical documentation (but it is out of the scope of comments anyway). Don't hide important information into comments, give it its own status. Don't clutter your code with comments. IMHO.
    • I've used some of the corallaries to this comment, e.g.

      /*Be afraid. Be very afraid.*/

      Once I actually did use the "/* you are not expected . . ." comment and got a severe talkin'-to by my boss about being a "team player". After that incident, I only commented in Latin and Klingon for that employer.

  • Comments tell reason. (Score:5, Insightful)

    by Daniel_Staal ( 609844 ) <DStaal@usa.net> on Wednesday November 30, 2005 @12:02PM (#14147460)
    The code can tell me what it is doing, but it can't tell me what it is supposed to be doing. The comment should tell me why the code is doing what it is doing. Then I can look at the comment and code together and tell whether the code is right. (And the comment won't have to change as I modify the code: It either stays because the why still exists, or it is removed because it doesn't.)
  • Learn to write Submissions [slashdot.org] first.

  • ...when you can code that way?

    "How to decrypt a DVD: in haiku form". [cmu.edu] It's quite elegant, really.

  • // Redundant.comment while(story = slashdot.getStory()) { story.read(); eyes.roll(); }

  • Three Books to Read (Score:3, Informative)

    by CortoMaltese ( 828267 ) on Wednesday November 30, 2005 @12:05PM (#14147494)
    Three pretty good books that have insightful views on how to write readable code and comment it appropriately:

    In short, they all suggest writing readable code is more important than commenting spaghetti, but there are also good points on commenting. (Can't be bothered to copy-paste them here, though, see for yourself.)

  • Comments First (Score:5, Insightful)

    by Doc Ruby ( 173196 ) on Wednesday November 30, 2005 @12:06PM (#14147500) Homepage Journal
    Good comments are written first, before the code, describing what the following code does. It is gramatically correct, punctuated, easy for a stranger to read. It says what the following code does in terms of the real world, not just in terms of other code, unless the sole purpose of the code is to connect other code without relation to anything expressible in real world terms. I prefer my comments to be in the present tense, as if they could be directly compiled themselves. I put comments inside practically every block, like function definitions, loops, conditionals. I often put comment labels after block closers, especially complex conditional sets, embedded loops and functions. That labeling makes it easier to keep track of context within which variables, their scope and the "current task" are in operation. I'd rather spend a few more seconds typing up front, and save a lot of scrolling and delimiter-matching later (not to mention reducing confusion and mistakes).

    Code gets shuffled around in different order, read by strangers, and reread much later by yourself, often after you've changed by experience (either in programming or in the task being programmed). Writing the code first is a good way to outline the program, and to detect flaws in your approach. It also gets a little bit of the program done, on screen where you can see it. Often coding to support the comments is more like a cleanup task than starting from scratch.

    • Re: Comments First (Score:5, Insightful)

      by Black Parrot ( 19622 ) on Wednesday November 30, 2005 @12:11PM (#14147549)
      > Good comments are written first, before the code

      When implementing a big program or non-trivial algorithm, I start the file with comments that end up serving as an outline for the code I insert afterward. It helps clarify my thoughts about how I'm going to go about it, and of course keeps me from forgetting anything.

    • Re:Comments First (Score:5, Insightful)

      by Henrik S. Hansen ( 775975 ) <hsh@member.fsf.org> on Wednesday November 30, 2005 @03:38PM (#14149652) Homepage
      Good comments are written first, before the code, describing what the following code does.

      That's some of the worst advice I have seen wrt. code commenting. Comments should never describe what the code does. If it is not obvious from the code, it should be refactored.

      The strategy of verbose and essentially redundant comments are bound to end up in outdated and/or useless comments. If such a practice is employed in industry, forcing people to comment every loop, etc. as you describe, I'm certain there would be a lot of useless comments.

      People will simply not do something, which they cannot see how they would later benefit from. Classic CSCW problem.

      • Re:Comments First (Score:3, Insightful)

        by booch ( 4157 )
        Comments should never describe what the code does.

        It seems that most folks here believe that -- that you should only comment on why you're doing things, not what you're doing. But I think that's a bad idea. For example, let's say you've got some "code" that says:

        Combine an egg, some flour, some milk, some sugar, ...

        I would contend that the comment should be "make a cake". I suppose you could contend that tells why we're combining the ingredients, but I think it's more clear to say that that is what we're do

      • Hard problems (Score:3, Insightful)

        by Dire Bonobo ( 812883 )
        > If it is not obvious from the code, it should be refactored.

        If it is obvious from the code, your project is too simple.

        (Flippant, but not totally false. I work on research code that does...significantly complicated things. It can be hard enough for me to keep track of the interactions of the algorithms even when I'm designing them on paper; translate them into code, and the result is not at all trivial.

        What my code does can be hard to understand when I've made a serious effort to clearly expla

  • Haiku? (Score:4, Funny)

    by Daedala ( 819156 ) on Wednesday November 30, 2005 @12:10PM (#14147544)
    Remember the seasonal reference!

    Begin declaring
    Global integers, constant
    As the winter rain

    Check for null values
    That will cause problems later
    Cherry blossoms fall

  • One good reason (Score:3, Informative)

    by Billosaur ( 927319 ) * <<wgrother> <at> <optonline.net>> on Wednesday November 30, 2005 @12:11PM (#14147553) Journal

    You should write comments because some day you're not going to be doing your job anymore, perhaps because you started your own rock band, or won the lottery, or the company decided they could get someone cheaper to do your work. In any case, some unfortunate soul (and I've been this person more than once) has to come in and maintain and expand your code. And in most cases we're bright and we know our languages pretty well, but we can be a little slow on the uptake. In the end, we stare at your code and ask, simply: What the freak is going on here?!?!? Because we are not mind readers, and if we were, we probably wouldn't want to touch your mind because... ewwwwwwwww!

    Does this mean you have to do this?:

    my $i = 0; # initialize variable $i

    No! We're not retarded... we think. But if it's not trivially obvious what you're doing somewhere in your code, please feel free to let us in on it. We would appreciate it.

  • I've written a lot of comments, and most of it was useless. It helps when you're looking at the code itself, but you missed the larger context unless every comment was mindnumbingly detailed. That type of comment is a pain to write and essentially unmaintainable.

    Javadoc (and similar well-supported systems) is godsend. You still want to have some comments within your code, but the real power is in the generated documents that give you the larger picture. It's not complete -- you still want to know the ov
  • comments in haiku
    not for any good reason
    I was very bored

    (And yes, I have done this. The bit above and several others are, as far as I know, still in some shipping management system for a certain multinational mining corporation.)

  • © Leo Plotkin

  • Humour in the Linux kernel (Score:5, Funny)

    by Mr_Silver ( 213637 ) on Wednesday November 30, 2005 @12:26PM (#14147713)
    This made me smile (in a rather sad way)...
    static void happy_meal_tcvr_write(struct happy_meal *hp, unsigned long tregs, int reg, unsigned short value)
    {
    int tries = TCVR_WRITE_TRIES;

    ASD(("happy_meal_tcvr_write: reg=0x%02x value=%04xn", reg, value));

    /* Welcome to Sun Microsystems, can I take your order please? */
    if (!hp->happy_flags & HFLAG_FENABLE)
    return happy_meal_bb_write(hp, tregs, reg, value);

    /* Would you like fries with that? */
    hme_write32(hp, tregs + TCVR_FRAME, (FRAME_WRITE | (hp->paddr
    Mind you, it's not a comment but this one was good for printer status:
    static char *usblp_messages[] = { "ok", "out of paper", "off-line", "on fire" };

  • 'Why', not 'How' (Score:5, Insightful)

    by lawpoop ( 604919 ) on Wednesday November 30, 2005 @12:34PM (#14147784) Homepage Journal
    The code is the 'How'. What the reader needs to know is 'Why' you are taking these steps. What larger goal are you accomplishing? What is the purpose of this code? What is its justification for existance?

    Fill in this blank: "If were weren't running this code right here right now, we wouldn't be able to do _____. We could have done it this other way, but we chose this method because of X, Y, and Z.

    In a real world example, code is like "Turn left, Go to High Street, turn right, continue on to 1122 High St, pull into the driveway, and park the vehicle." Those are the steps taken, but the goal you are acommplishing is "We want to return the library books, so we are going to drive the books to the library using the car."

    OK, so why are we taking the books to the library? Ultimately all comments will filter up to the goals of the application. They are all nested subgoals of the design specs.

  • Comments are Critical to larger scale projects (Score:4, Insightful)

    by localman ( 111171 ) on Wednesday November 30, 2005 @12:52PM (#14147978) Homepage
    Sure, well written code should read clearly and be clear about what is happening at every step. But in any larger scale project, no matter how well you make your data structures or how cleanly you encapsulate, eventually you'll code things where the motivation isn't clear.

    Good comments don't talk about the code itself, they talk about why the code is doing what it's doing. What the code is doing should be obvious if it's well written, but I've never written a code file that couldn't benefit from a little english exposition.

    Cheers.

  • "should I write comments?" (Score:3, Insightful)

    by tomstdenis ( 446163 ) <tomstdenis@gma[ ]com ['il.' in gap]> on Wednesday November 30, 2005 @01:01PM (#14148068) Homepage
    Boom, you're fired.  If you have to ask that you're clearly incompetent.

    As to what a good comment is, it's something that gives context to a section of code.  Comments aren't supposed to "explain" every step of an algorithm but rather explain why they're there...

    e.g.

    // for loop from 1 to 5
    for (i = 0; i < 5; i++)
       // strcmp for "key"
       if (!strcmp(strings[i], "key")) dowork();

    Could be written better as

    // we are going to look for the string "key" in the array
    for (i = 0; i < 5; i++)
       if (!strcmp(strings[i], "keys")) dowork();

    (better yet is to replace '5' with some constant or other label).

    In cryptographic tasks I assume the reader has the RFC [or other spec] handy and I just explain what parts of the standard I'm fulfilling, e.g.

    // step 3c, xor key with 0x5e
    for (i = 0; i < keylen; i++) key[i] ^= 0x5e

    That way the reader can follow my code against the spec quicker.

    If you're not capable of these sorts of comments it's because you don't think like a developer.  You're slinging one line of code against another instead of properly breaking your task down into many smaller more modular tasks which can then be easily expressed on their own.

    Tom

  • lazy programmers (Score:5, Insightful)

    by MatD ( 895409 ) on Wednesday November 30, 2005 @01:04PM (#14148098)
    People use the 'code should be self documenting' excuse because they are lazy and don't want to take the time to actually write documentation.

    If you are programming anything non-trivial, you are going to have sections of code that are obscure, and when you have to go back and fix a bug, or add functionality, you won't have any idea what the hell you were doing.

    For example, I've written code that had to run on displays with 256 color palettes in windows. It involved saving the current palette when the window gained focus, and then restoring it when the window lost focus. But I couldn't even tell you how I did that now. If I had to go back and look at that code today, I'd have no idea what I was thinking. I do recall that is wasn't actually very many lines of code.

    Back before UML was a common thing, I used to 'write' my code in comments and stubs, as a design. After I could read through the code as a narrative of what my app/service/dll did, I would actually fill in the stubs to make it work. This ended up saving me a lot of time in the long run, as I didn't really have much refactoring work to do while coding.

  • Unified theory of commenting (Score:5, Funny)

    by awtbfb ( 586638 ) on Wednesday November 30, 2005 @01:06PM (#14148114)
    // If you can't follow this, go ask CowboyNeal

  • My haiku (Score:5, Funny)

    by timbck2 ( 233967 ) <<moc.liamg> <ta> <2kcbmit>> on Wednesday November 30, 2005 @01:32PM (#14148417) Homepage
    So many good posts --
    Damn! I wish I had mod points!
    Better luck next time.

  • I have to tell this story... (Score:5, Funny)

    by RetiredMidn ( 441788 ) * on Wednesday November 30, 2005 @01:53PM (#14148637) Homepage
    ...if I haven't already.

    Back in the 70's, I worked the Help Desk at my college's computer center. I was approached by a student taking the entry-level programming class, which taught FORTRAN; programs for the class were written on punched cards (!) and submitted to our RCA Spectra for batch processing.

    Anyway, this guy came to me with a question about a cryptic compiler error message (maybe that's redundant). I asked to look at his listing, and found the problem easily enough, but I was intrigued to see that his code was double spaced! (See it coming, yet?) I wanted to figure out how he did it, because I thought it would be useful in my own work to leave room for writing notes on my listings when I looked at them back in my dorm room.

    I couldn't find any special options on his command card (the first card in the deck that specified how the deck was to be processed; I finally realized that every other line was a blank comment line. (A "C" in column one, and nothing else on the line/card, for you young'uns).

    I couldn't imaging taking the time at the card punch to type just "C", then feed a new card (which took a couple of seconds) between every line of code, so I asked him why he had bothered.

    His answer...

    [...wait for it...]

    "The professor said the program would be easier to debug if we included a lot of comments."

    P.S. The program, about 15-20 lines long, was devoid of actual comment text.

  • Overcomment everything (Score:5, Interesting)

    by Animats ( 122034 ) on Wednesday November 30, 2005 @02:16PM (#14148895) Homepage
    Of course you write comments. Usually more comments than code. Don't look for excuses not to comment.

    Some comments I've written:

    • From a physics engine [animats.com]:
      // The contact force component is aligned with the vector between
      // the two closest points. The frictional force is in a plane
      // perpendicular to that vector and through the midpoint of pnt0-pnt1,
      // The frictional force vector is opposite the velocity vector
      // component in the friction plane.

      // Witness point checks.
      // All witness points must be on their polyhedron's side of the
      // separating plane.

      Here the purpose of the comments is to explain the math.

    • From the control code for a DARPA Grand Challenge vehicle [overbot.com]. Here's some code I wasn't happy with, so that's clearly noted.
      // constructPath2 -- reactive obstacle avoidance and path planning
      // - the hard cases
      //
      // Called when we have to do some obstacle avoidance
      //
      // Path is an output only.
      //
      // First pass tries to find some path that will work within the turning limits.
      // If that fails, we try "brake then steer" mode - look for the longest path
      // in any direction, regardless of dynamics limits, and slam on the brakes
      // while turning. The actual steering command will be limited later.
      // ***MAKE SURE THAT CHECK IS MADE***
      //
      // ***NEEDS WORK***
      // ***SEARCHING OUTSIDE LIMITS WILL ALWAYS FAIL***
      //
    • Finally, here's some Perl code, part of the code that runs Downside. [downside.com]
      #
      # extractsecurityclass -- extract class of a NASDAQ security
      #
      # Foreign and bank securities aren't filed with the SEC, so
      # we need to note this. There are also test and statistics items that
      # aren't real securities.
      #
      # Note that the test for "bank" is rather poor. NASDAQ used to
      # identify banks using a column in the table, but they no longer do so.
      #
      sub extractsecurityclass($)
      { my $vals = shift;
      ## Check for symbols that don't file with the SEC
      if (${$vals}{'test_issue'} ne 'N') { return('test'); } ## is test
      (We have to stop there; Slashdot's "lameness filter" rejects Perl code.)

    All code should have well-written comments. As Wirth pointed out years ago, people who can't express themselves well in their native language are generally poor programmers.

  • Article Author on Crack (Score:5, Insightful)

    by dmatos ( 232892 ) on Wednesday November 30, 2005 @02:51PM (#14149249)
    As per the subject line, the author of this article is on crack. I'm not going to argue the why's and wherefores of his text, but I have a major objection to his "when". He states that the best time to comment code is once it's all done, and you're just about to submit it. WRONG!

    Has he ever worked on a major project? One that cannot be held in one brain in its entirety at one point in time? START with the comments. Start with the program architecture. Decide what each part will do. Write out how each part will accomplish its goals. Then, copy/paste that into your editor, and write the code to match the comments.

    Believe me, if you can plan out how everything will work in the first place, and then just follow your plan, the whole project will be much easier. An added bonus is that the code comments just come straight from your design document. Of course, from the tone of the article, I'd guess that this guy's response would be "What design document?"

Slashdot Top Deals

Receiving a million dollars tax free will make you feel better than being flat broke and having a stomach ache. -- Dolph Sharp, "I'm O.K., You're Not So Hot"

Close