Slashdot is powered by your submissions, so send in your scoop

 


Forgot your password?
Close
typodupeerror
×
Programming Technology

Comments are More Important than Code 1021

Posted by timothy from the if-you-disagree-provide-comments dept.
CowboyRobot writes "I was going through some code from 2002, frustrated at the lack of comments, cursing the moron who put this spaghetti together, only to realize later that I was the moron who had written it. An essay titled Comments Are More Important Than Code goes through the arguments that seem obvious only in hindsight - that 'self-documenting' code is good but not enough, that we should be able to write code based on good documentation, not the other way around, and that the thing that separates human-written code from computer-generated code is that our stuff is readable to future programmers. But I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized. Who's right?"
This discussion has been archived. No new comments can be posted.

Comments are More Important than Code More

Comments are More Important than Code

Comments Filter:

  • Even more annoying... (Score:5, Funny)

    by Anonymous Coward on Tuesday April 26, 2005 @09:12PM (#12354434)
    I used to grade student's code as a TA at my university, and I'll tell you what is more annoying than NO comments, this:

    printf("Encrypt message..."); /* print "Encrypt message..." to the console */

    and then followed by about 150 lines of uncommented spaghetti code
    • Well then, just employ a code comment moderation system.

    • Re:Even more annoying... (Score:5, Insightful)

      by Klar ( 522420 ) <curchin @ g m a i l .com> on Tuesday April 26, 2005 @09:22PM (#12354521) Homepage Journal
      hah I also grade as a university TA, and let me tell you what is more annoying than that... people who don't know how to indent their code, and want you to help debug it! Ahhhhh!!!!!

    • Re:Even more annoying... (Score:5, Insightful)

      by Anonymous Coward on Tuesday April 26, 2005 @09:46PM (#12354709)

      You know whose fault that is? The morons that mark you down if you don't comment trivial programs like Hello World.

      I actually ended up doing three introductory programming courses at college and university (overlap in curricula), and I've been marked down for not including this type of comment in all three courses.

      printf("Hello, world!\n"); /* send "Hello, world!" to the console and move to the next line. */

      The problem is that they try and teach you to write comments prematurely. When all most people on the course can write are programs like Hello World, they really can't see the use of comments and there are no good examples to give. The use of comments should come after things like functions etc IMHO, so that students can actually see how comments can be useful.

      • Re:Even more annoying... (Score:5, Insightful)

        by T-Ranger ( 10520 ) <(jeffw) (at) (chebucto.ns.ca)> on Tuesday April 26, 2005 @10:56PM (#12355211) Homepage
        Ive been in enough classes this year (well below my level.. dammit, I need the "letters") that Ive come to the conclusion that introductory programming courses are taught all wrong.

        Write 5 lines. Write 20 lines. Write 100 lines. Of useless and pointless code.

        What should be done is: Take this 1000 line programme. Add on 5 lines. Add on 20 lines. Add on 100 lines. Beacuse that would require being able to read code, too. Being able to understand what is already there is frequently more then half the battle. Saying "What the fuck does this mean?" a few dozen times is the only way to get to write comments. Being a sysadmin, rather then a full time programmer, this took me litteraly years to learn. And it was usualy "What the fuck were you doing here, brain? Dammit, one of these days were going to have to start commenting our code."

        About 6 months ago, I read through a project request on one of these ebay-for-coders sites. Language optional; 1 comment per 5 LOC, but if using Perl, 1 comment per 2 LOC.. With requrements like that you are only asking to get BS comments like "Print X to the console".

        • Re:Even more annoying... (Score:5, Interesting)

          by tomhudson ( 43916 ) <barbara DOT huds ... a-hudson DOT com> on Tuesday April 26, 2005 @11:07PM (#12355317) Journal
          What should be done is: Take this 1000 line programme. Add on 5 lines. Add on 20 lines. Add on 100 lines.
          Better yet - remove 5 lines. remove 20 lines. remove half the lines ... and it better still work!

        • Actually, you illustrate a bigger problem (Score:5, Interesting)

          by Moraelin ( 679338 ) on Wednesday April 27, 2005 @02:45AM (#12356530) Journal
          It's not just that the programs to write are small, it's that they're write-only. You write them once, get graded, that's it. We churn generation after generation of students who are taught that code is written once, then never ever maintained.

          Sure, you learn lots of things about design, software engineering, etc, in university, but they're pure theory. And seemingly useless theory at the moment. There is _nothing_ to illustrate there why some code organization is good, and why spagetti code is bad. All those lessons about maintenance as wasted when you never have to maintain anything, nor ever write anything big enough.

          So while I'll say your idea does have merit, I think it can be done better. Don't just give them 1000 lines of someone else's code. Make them keep building and expanding the same program until the last year.

          E.g., ok, in introductory programming they had to write some 100 line trivial program. But don't throw it away. When the next course comes along, give them the assignment to change or expand that original program.

          E.g., if at some point you also get a computer graphics course, make them add a graphics module to that program. GUI programming? Sure, add a GUI to it. Database programming? Sure, make it save the data in a database. YACC? Ok, make them add a small scripting language to it. Different language? Make them port it to that language. Etc.

          Make it a part of the grade to explain _what_ had to be changed and _why_.

          Eventually it _will_ grow to be 1000 lines, and then it will grow even larger. And more importantly it'll be example of why code has to be readable and maintainable.

      • Re:Even more annoying... (Score:5, Insightful)

        by JohnsonWax ( 195390 ) on Tuesday April 26, 2005 @11:07PM (#12355314)
        The problem is that they try and teach you to write comments prematurely.

        No, the problem is that they try and teach you to write code prematurely.

        Document your application, requirements, constraints, and system interactions (what the engineer does). Then write the code (what the coder does).

        What you will quickly learn is that it's better to be the engineer than the coder. What you'll realize is that the engineer is the client-side guy that figures out how to solve the challenge presented and the coder is the guy who can live in Manipal.

        The computer scientist is another guy altogether, that sets the boundaries within which the engineer must work and provides many of the tools.

        Somehow CS education has gotten horribly derailed, and asks students to combine the equivalents of electromagnetic theory, power system design, and basic home wiring in one curriculum. No wonder enrollments are plummeting - nobody knows what a CS major is or should do.

      • here's some Pretty Evil Shit - Re:Even more annoyi (Score:5, Funny)

        by Fubari ( 196373 ) on Wednesday April 27, 2005 @01:01AM (#12356023)
        Here is an example of some Pretty Evil Shit:
        I want to laugh when I read it.
        Some of it is funny.
        Some of it is just scary.
        The human mind can be a freakishly messed up thing.
        http://mindprod.com/unmaindocumentation.html [mindprod.com]
        It is part of a larger essay about writting crappy code.
        Anybody that even comes close to software development
        should check it out.

        --- begin excerpts ---
        Avoid Documenting the "Obvious" : : If, for example, you were
        writing an airline reservation system, make sure there are at
        least 25 places in the code that need to be modified if you were
        to add another airline. Never document where they are. People who
        come after you have no business modifying your code without
        thoroughly understanding every line of it.

        Units of Measure : : Never document the units of measure of any
        variable, input, output or parameter. e.g. feet, metres, cartons.
        This is not so important in bean counting, but it is very important
        in engineering work.

        As a corollary, never document the units of measure of any conversion
        constants, or how the values were derived.

        It is mild cheating, but very effective, to salt the code with some
        incorrect units of measure in the comments.

        If you are feeling particularly malicious, make up your own unit of
        measure; name it after yourself or some obscure person and never
        define it. If somebody challenges you, tell them you did so that
        you could use integer rather than floating point arithmetic.

        On the Proper Use of Design Documents : : When implementing a very
        complicated algorithm, use the classic software engineering principles
        of doing a sound design before beginning coding. Write an extremely
        detailed design document that describes each step in a very complicated
        algorithm. The more detailed this document is, the better.

        In fact, the design doc should break the algorithm down into a hierarchy
        of structured steps, described in a hierarchy of auto-numbered individual
        paragraphs in the document. Use headings at least 5 deep. Make sure that
        when you are done, you have broken the structure down so completely that
        there are over 500 such auto-numbered paragraphs.

        For example, one paragraph might be: (this is a real example)
        1.2.4.6.3.13 - Display all impacts for activity where selected
        mitigations can apply (short pseudocode omitted).
        then... (and this is the kicker) when you write the code, for each of these paragraphs
        you write a corresponding global function named:
        Act1_2_4_6_3_13()
        Do not document these functions. After all, that's what the
        design document is for!

        Since the design doc is auto-numbered, it will be extremely difficult
        to keep it up to date with changes in the code (because the function
        names, of course, are static, not auto-numbered.) This isn't a problem
        for you because you will not try to keep the document up to date.
        In fact, do everything you can to destroy all traces of the document.

        Those who come after you should only be able to find one or two
        contradictory, early drafts of the design document hidden on some
        dusty shelving in the back room near the dead 286 computers.
        --- end excerpts ---
    • Don't forget about students who use assert()'s for validating user input!

    • Re:Even more annoying... (Score:5, Funny)

      by el-spectre ( 668104 ) on Tuesday April 26, 2005 @10:18PM (#12354924) Journal
      As a freshman I had a professor who kept giving me shit about not having enough comments, so my next program looked something like this: ...
      a=5; //assign integer variable 'a' a value of 5
      b=2; //assign integer variable 'b' a value of 2
      print(a+b); //print to the console the sum of integer variable 'a' and integer variable 'b' ...

      and so on, for about 200 lines. Worthless commenting? Sure, and childish too... but it was amusing and I never got docked for insufficient commenting again :)

    • Re:Even more annoying... (Score:4, Funny)

      by Ratbert42 ( 452340 ) on Tuesday April 26, 2005 @11:03PM (#12355269)
      I just ripped this comment out of our code today: // close the file
      closeFile();

    • Re:Even more annoying... (Score:5, Interesting)

      by rve ( 4436 ) on Wednesday April 27, 2005 @12:41AM (#12355943)
      At work, we are not allowed to use comments in the code.

      Allowing comments would "encourage coders to use clever tricks" according to the technical director.

  • Gotta document that code... (Score:5, Interesting)

    by TripMaster Monkey ( 862126 ) * on Tuesday April 26, 2005 @09:12PM (#12354435)
    From the Summary:
    ...I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized. Who's right?


    You are. No question.

    I have a saying I like to use when people (usually managers) try to persuade me to take the quick/cheap way out:


    "Any time/money you save by cheaping out now, you'll wind up having to pay back twice over on the back end."


    I've yet to see this maxim disproved, and it's just as applicable to coding as it is to anything else. Your colleagues are certainly correct when they state that the code must be well organized, but this simply isn't enough. If you don't put in the necessary time (minimal, really) to properly document your code, you'll wind up spending a lot of time trying to figure out just what you did and why. Also, even if you can remember exactly what your code is all about, the guy that comes after you probably won't...proper documentation is professional courtesy. I suppose they'll learn after they spend a few hours puzzling over a piece of old code (that's how I learned...:P ). Sooner or later, not documenting properly will bite them in the ass.

    • Re:Gotta document that code... (Score:5, Insightful)

      by Fjornir ( 516960 ) on Tuesday April 26, 2005 @09:14PM (#12354446)
      The canonical form of your maxim is "If you don't have time to do it right the first time, when will you find time to do it again?". The correlary is: "The problem with quick and dirty is that dirty remains long after quick is forgotten."
      • And don't forget the maxim that seems to be prevalent everywhere, even though everyone "knows" this shouldn't be....

        "There's never enough time to do it right, but always enough money to do it twice."
    • Judging from your indenting, I'm sure glad I don't have to read YOUR code.

    • Re:Gotta document that code... (Score:5, Insightful)

      by RootsLINUX ( 854452 ) <rootslinux@NospaM.gmail.com> on Tuesday April 26, 2005 @09:21PM (#12354510) Homepage
      I agree. Giving your variables descriptive names is a good practice, but it's not nearly enough "commenting". If you have a piece of code that manipulates the values of those descriptive variables with bit masks to spit out a value, how is someone supposed to know what you just did? I think the adage "you don't document your code, but you code your document" is a little extreme, but it gets across the importance of code documentation. I'm working on an open source project of my own right now. I went back to modify a piece of code that I hadn't touched for nearly 4 months, only to make absolutely no sense of what the hell I was doing there. Luckly I commented it extremely well so after reading the comments I was able to get that "Oh yeah..." feeling and make the appropriate modifications without breaking the code. Lesson: commenting code may take you some more time now, but it's going to save you a hell of a lot of time later.

      On that topic, what are some good examples of well-commented code? Rather than just see words, I'd rather see real-life applications of these practices. For starters, here's typically how much I comment my code: Allacrost source code [sourceforge.net] (note: not all files were written by me, by I try to stress heavy commenting on the rest of my team)

      • Re:Gotta document that code... (Score:5, Insightful)

        by gregmac ( 629064 ) on Tuesday April 26, 2005 @11:05PM (#12355292) Homepage
        Rather than just see words, I'd rather see real-life applications of these practices. For starters, here's typically how much I comment my code:
        tmp = last_update; // tmp = last update time
        last_update = SDL_GetTicks(); // Set the last update time to now
        tmp = last_update - tmp; // tmp = difference between now and last update
        fps_timer += tmp; // Increase our fps millisecond timer
        fps_counter++; // Increase our frame count


        There's also something as far as too much commenting. Don't get me wrong, I can't stand uncommented code. I learnt, like most people, the hard way -- go back to edit something I did 6 months ago, and have no idea what's happening.

        But I don't think this is useful: // tmp = last update time. You've just spelled out in english what tmp = last_update; says in code. Comments don't add anything if you can just read the code and figure it out. If anything, it's a waste of time.

        Here's my version of your same section
        // find the time since our last update
        tmp = last_update;
        last_update = SDL_GetTicks(); // now
        tmp = last_update - tmp;
        // add time and increment counter
        fps_timer += tmp;
        fps_counter++;
        This isn't really the greatest example, but I like to comment sections of code. The details can be read by looking through the code, with "hints" as needed (for example, reminding me that SDL_GetTicks() is the current time).

        Well commented blocks mean you can skim through the code, getting a quick overview of what's happening, without having to read in much detail.
        // find matching entry in hash table
        while (....
        .....
        .....
        }
        You don't have to care about the details of the look, you just know by the time you hit the } you've found what you wanted.

        Don't take this personally or anything. Your code is very readable.. there's just lots of extra comments (granted, I've seen worse) that are really just not worth putting in.

        (also, proper indenting is as, if not more, important.. of course, /. is butchering my indenting.. so please don't harass me about that because i couldn't agree with you more ;) )

        • Re:Gotta document that code... (Score:4, Insightful)

          by ComputerSlicer23 ( 516509 ) on Wednesday April 27, 2005 @12:38AM (#12355927)
          The concept I remember most from "Code Complete" is comments should tell you why or what are you doing something, but it shouldn't tell you how you are doing. The how should be obvious from the code.

          Never tell me you are adding shifting the varaible by 4 bits, instead tell me, you are converting from bytes to 16 byte blocks due to a chunks size conversion because that's the size the output device expects blocks to be written in.

          Don't tell me you are swapping variables, tell me why the values should be exchanged.

          Don't tell me you searching for the max value, tell me what the max value is used for when you find it. That sort of concept.

          One easy way to do that, is to look at code and the comments. If the code and the comments could get out of sync because you changed the implementation, the comment is wrong. You documented the how not the what.

          There are cases where the how is important, especially when there are things where the "how" doesn't behave naturally. Oh, this sorts numbers, but it is intentionally sorting the ASCII values of the numbers when represented as a string. That'd be very useful to know. I'd expect a sort to work based on the binary values.

          The other rule I remember from code complete, and from "Writting Solid Code", was the concept of laying out the pseudo code that explained what you wanted to do at a high level. Then filling in between the comments with the implementation. It was a very good way to end up with documented code.

          Kirby

        • Re:Gotta document that code... (Score:5, Insightful)

          by slashdot.org ( 321932 ) on Wednesday April 27, 2005 @12:42AM (#12355945) Homepage Journal
          Here's what my version would look like:
          //---
          // TODO: gracefully handle wrap-around of SDL_GetTicks()
          // not implemented yet because it only happens every 40 years
          //---
          tmp = last_update;
          last_update = SDL_GetTicks();
          tmp = last_update - tmp;
          fps_millis_timer += tmp;
          fps_counter++;
          My philosophy is that:
          1) production code is not a tutorial of the C(++) language. It's okay to assume the reader knows their stuff. A bad example:
          tmp = last_update; // tmp = last update time
          2) production code is not documentation on the APIs that it uses. APIs have their own documentation, the reader either is familiar with it, or can find documentation. A bad example:
          last_update = SDL_GetTicks(); // now
          If the API is only used in one file, then you could point at the documentation right where the header is included. If it's used on a project level, then it should be pointed to at the project documentation.
          3) comments are just as much about why you didn't do something a certain way as it is about why you did do something a certain way.
          4) the obvious; name your variables correctly. Instead of:
          fps_timer += tmp; // Increase our fps millisecond timer
          use
          fps_millis_timer += tmp;
          5) if you are implementing using a spec, somewhere in the top of the file describe the revision of the spec. Additional comments can describe the section of the spec that they relate to.
          For example:
          // Init GDT, see section 6.3.1
          virtual_machine.gdt.base = base;
          virtual_machine.gdt.limit = limit;
          6) NEVER put actual values in comments. For example:
          com1.baudrate = 9600; //set baudrate to 9600
          The code already shows the actual value, and all too often the comment doesn't get updated.
          Sometimes it's okay to list the possible values:
          out_p16_d8( base + CSR, 0x66 ); //0x61 = 1x, 0x62 = 2x, 0x66 = 4x, other val illegal
          but I only prefer that when this is the _only_ place where it is used. Otherwise you'd use enums and/or refer to the documentation section/page
          7) write top level documentation to explain what the software is actually supposed to do. It's amazing how often this is missing. Write one bloody page that describes to a programmer that doesn't know ANYTHING about the software what the hell it's supposed to do, and how it's accomplishing this. It also helps tremendously if every file has a little description in the header. And I'm not talking about what license the code is distributed under.
    • Comments are essential to maintaining any project.

      It's annoying when I go to the person who wrote a chunk of code fom a couple months ago to ask them some questions, they look at the code and have no idea why they were doing what they were doing.

      I've always followed the philosphy that I should write and comment code so that someone who wasn't a programmer could read it and understand what was going on. This makes it very easy to go back even years and know exactly what the code was doing and why it was do

    • Re:Gotta document that code... (Score:5, Insightful)

      by snorklewacker ( 836663 ) on Tuesday April 26, 2005 @09:36PM (#12354641)
      You are. No question.

      Hello. I question. Look, if you need comments to explain the code flow because your method spans four screens and has six levels of conditionals in two levels of loops, all the comments in the world won't help you.

      Especially if you change the code and now the comments are wrong

      I have had the joy of maintaining lovingly commented code with all these huge blocks at the start showing what args get passed and what happens, and I can't understand a god damned thing about what it's doing, because the code all looks like
      (void *((ebuf->qs) > VRT_FBUF) ? etranf(&q) ...
      All generalisms are wrong.
      • The code needs to be well documented, where "well" means both "correctly" and "frequently." Lots and lots of poor documentation is just as bad as little or no documentation. And documentation, no matter how well done, will not fix lousy code.

        So I don't question. The story poster is correct. Code needs to be well documented, and neither good organization nor descriptive variable names is a sufficient replacement for documentation. But you're absolutely correct too that documentation is only a small pa
      • Hello. I question. Look, if you need comments to explain the code flow because your method spans four screens and has six levels of conditionals in two levels of loops, all the comments in the world won't help you.

        That's not true. One line comments won't help, but a large descriptive comments will. If you can explain the code by talking about it, then you can explain the code by writing about it.

        Especially if you change the code and now the comments are wrong

        You're incompetent if you don't change th

        • A database backend would go a long ways... (Score:5, Interesting)

          by mosel-saar-ruwer ( 732341 ) on Tuesday April 26, 2005 @10:58PM (#12355228)

          GRANDPARENT: Especially if you change the code and now the comments are wrong

          PARENT: You're incompetent if you don't change the comments to match the code. You're equally incompetent if you come across incorrect comments and leave them in. You're supposed to the job, so do it...

          PARENT: As Fred Brooks said, "There is no silver bullet."

          A database backend would go a long ways towards providing a silver bullet, i.e. if instead of writing your code to an ASCII text file, you were writing to a document management system that kept doubly linked associations between the lines of code and the comments associated with those lines of code, and if code/comment pairs had dirty bits, so that if you changed one [e.g. the code], then the dirty bit wouldn't get changed to clean until you verified that the other [e.g. the comment] was correct, then that would go a long way towards solving the problem.

          I think we are still in the infancy of code/documentation/database integration, however.

      • Re:Gotta document that code... (Score:5, Funny)

        by spammacus ( 805242 ) on Tuesday April 26, 2005 @11:03PM (#12355267)

        All generalisms are wrong.

        Isn't that a paradox? :)

    • Re:Gotta document that code... (Score:5, Insightful)

      by rkcallaghan ( 858110 ) on Tuesday April 26, 2005 @09:47PM (#12354721)
      Sooner or later, not documenting properly will bite them in the ass.

      Actually I have found that more often than not, not documenting properly only bites someone else in the ass.

      This is likely the source of the problem, and the least likely to change. I suppose it could be part of the QA process to check for notation on code, but I somehow suspect that with programming jobs on a one way trip to Bangalore that readability it secondary to "works cheap."

      ~Rebecca
    • If you don't put in the necessary time [...] to properly document your code, you'll wind up spending a lot of time trying to figure out just what you did and why

      The corollary to this is the need to maintain existing comments when the code is changed. Misleading/outdated comments can sometimes be worse than none at all.

      proper documentation is professional courtesy

      I couldn't agree more. Good documentation gives you context and insight into the motivation of a past developer, which can be priceless when
    • The only time comments should be in code, is when the effect of the code is different than it appears to be - different than what a reasonably skilled programmer would expect. That is the only reasonable use for comments. For reference, here is a quick list of arguments and my canned responses:
      I need comments because I can't understand the code otherwise.
      You should be writing simpler code. If the code is too hard to understand by itself, then it is your job to make it simpler.
      It's not the code t

      • Re:Gotta document that code... (Score:5, Interesting)

        by jesup ( 8690 ) * <randellslashdot@ ... p.org minus city> on Tuesday April 26, 2005 @11:08PM (#12355325) Homepage
        comments can lie
        I worked with a programmer who disliked comments so much he'd remove them before looking at a function. Ok. So I wrote some code and he came to me and said "why do you have an empty else case?" I was puzzled, then realized that I'd written something like this:
        else
        {
        /* we don't have to do anything in the else case because of x y and z */
        }
        where x y and z would be non-obvious to anyone who wasn't fully immersed in this code. He's run it through a filter that removed all comments. He was a genius programmer - but wrote code that almost no one else could ever maintain. Tons of reliances on edge conditions without comment, reuse of generically-named variables (1 and 2 character names), tricky (but efficient) algorithms. So far as I know, I was the only one there ever to manage to really grok his code, and that required days of immersing myself.

        x = x++; // add one to x
        is obviously not useful.
        // Test FU_E (End bit) after FU_A/FU_B test! If there's a gap, do not consider
        // hitting the End bit a marker to stop - continue until we see another
        // packet/timestamp (in which case we return TRUE), or until we are
        // at the end of the buffer (in which case we return FALSE and keep
        // hoping to assemble it).
        if (((*curr)->GetPayload()[1] & FU_E_BIT) && !gap)
        break; // no error in fragment
        // if there's a gap we still won't return true unless
        // we find a non-fragment packet (or one from another fragment!)
        This is an example of a useful comment - and yes, it has to be maintained if the line of source were to change. I chose that at random; there are better examples - such as explaining what the edge cases are (especially if not handled), and under what circumstances they would become relevant, and how they could be dealt with then.

        Please excuse the incorrent indenting above; "<ecode>" doesn't work exactly like 'pre'

        • Re:Gotta document that code... (Score:5, Insightful)

          by skraps ( 650379 ) on Tuesday April 26, 2005 @11:50PM (#12355609)
          That comment is a good match for the code it is with. I never write comments like that unless dealing with a 3rd party interface, or something else that is a brick wall I can't refactor across, and there is something very quirky or unusual about it. The 'if' in the last snippet you quoted is very complex, and I would probably try to decompose it into a few functions and/or objects as necessary to make it clear what is happening. For example, you could start by replacing the 'if' with:
          if(message.is_complete())
          break;
          This clearly expresses the intent of the code you quoted (assuming I understood it correctly). Here, I've created a 'message' object to encapsulate some of the logic. The entire loop may be changed to look something like this:
          while(!message.is_complete())
          {
          packet_t packet=connection.get_next_packet();
          message.receive_packet(packet);
          }
          Now, the "is complete" decision making is abstracted to the "message", which seems to me the right place for that responsibility. Another thought is that the [1] should be changed. I'm guessing that you are referring to the second byte of the received packet, and using it as a flags field of some kind. If that is the case, why not go ahead and make a struct that represents the header layout, and reference the flags through a bitfield in the struct? If you do that,
          (*curr)->GetPayload()[1] & FU_E_BIT
          Becomes
          (*curr)->header->flag_end_of_message
          ...which seems clearer to me.

          You could continue along these lines, and get to a point where it would be obvious what the code does. The comment in that snippet also addressed "why", in addition to "how". I would move the "why" explanation into a document that defines the protocol.

        • Re:Gotta document that code... (Score:5, Informative)

          by Jeremi ( 14640 ) on Tuesday April 26, 2005 @11:51PM (#12355617) Homepage
          x = x++; // add one to x


          is obviously not useful


          Not only is the comment not useful, it's factually incorrect... the behaviour of that line of code is undefined [msdn.com].

  • Use long variable names (Score:3, Funny)

    by Joey7F ( 307495 ) on Tuesday April 26, 2005 @09:13PM (#12354439) Homepage Journal
    Just go ahead and use the long names, that alone will reduce documentation/commenting

    --Joey

    • Nah (Score:5, Funny)

      by Anonymous Coward on Tuesday April 26, 2005 @09:23PM (#12354531)
      Variable names should be proportional to the size of their scope within the code.

    • Re:Use long variable names (Score:5, Insightful)

      by p3d0 ( 42270 ) on Tuesday April 26, 2005 @09:45PM (#12354701)
      This same point arises every frigging time someone talks about comments. As I say every time: A variable name can only tell you what the variable is, not why you chose to make it that way.

      Now with that out of the way, here's my philosophy on variable names... Every variable name should be as long as necessary to describe what the variable is. Having said that, the shorter, the better. If you have a lot of long variable names, then you probably have not found the most elegant solution to your problem.

  • Comments more important? (Score:5, Funny)

    by Rollie Hawk ( 831376 ) on Tuesday April 26, 2005 @09:14PM (#12354441) Homepage
    Has he read the ones here?
    • Haven't you ever heard the maxim, "Debug code, not comments". It reflects the fundamental problem with comments.

      The problem with comments is there is no constraint to keep them...

      • Current
      • Correct
      • Meaningful
      • Unambiguous.

      Code Reviews help, but not enough.

      There is a better way. It is called Test Driven Development. Tests are the least ambiguous, most correct and current commentary on the code. They are also always at the correct (higher) semantic level than just paraphrasing the code.

      Given a choi

  • huh, just like /. (Score:5, Funny)

    by eobanb ( 823187 ) on Tuesday April 26, 2005 @09:14PM (#12354442) Homepage
    ...where comments are more important than articles.

  • Perl POD Documentation (Score:3, Interesting)

    by LogicX ( 8327 ) * <slashdot.logicx@us> on Tuesday April 26, 2005 @09:14PM (#12354444) Homepage Journal
    How about Perl's POD Documentation? I do a lot of hacking of Matt Simerson [simerson.net]'s Mail::Toaster [tnpi.biz] and Nictool [nictool.com] projects, and I find that the Perl POD Documentation system, combined with well-named variables is easy on the eyes, and leads to it being well interpreted by an outsider.

  • Comment. (Score:3, Insightful)

    by stealth.c ( 724419 ) on Tuesday April 26, 2005 @09:16PM (#12354454)
    Always comment. Always. I'm not a career coder, but I've done enough to know that if it's a project of any noticeable size at all, and you intend to read the code later, take the extra few seconds and COMMENT THE STUPID THING. It makes life a lot easier. The only thing that probably doesn't need commenting is a simple BAT file or a shell script. Comment!

  • Write code like someone else will maintain it (Score:5, Interesting)

    by John Seminal ( 698722 ) on Tuesday April 26, 2005 @09:18PM (#12354477) Journal
    that using short, descriptive variable names 'should' be enough as long as the code is well-organized.

    This works for code I write that nobody else will ever maintain. Even then I can get tripped up, I'll have to lean back in my chair and try to remember what I was thinking when I wrote the code.

    But if you write code you're getting paid for, or code for an organization, anything but personal stuff, write good comments. Variable names might give a good idea about what data the variable holds, but it does not tell us much about how it is used.

    When I took my first programming class, the most frustrating part was the documentation. I thought it was retarded and stupid and a waste of time. But now I realize it is very important once you write something more significant than "Hello World".

    • ..and try to remember what I was thinking when I wrote the code

      People sometimes forget that you are not only documenting WHAT the code is doing, but WHY you are doing it that way. You can usually figure out the what from the code itself, but trying to figure out the why can be next to impossible.

      I wrote some code years ago to calculate (Australian) Capital Gains Tax liabilities. I knew it would be a hassle to update the code when the tax laws were inevitably reviewed and updated, so I went out of my wa

  • Not necessarily comments... (Score:4, Interesting)

    by kwoo ( 641864 ) <{kjwcode} {at} {gmail.com}> on Tuesday April 26, 2005 @09:19PM (#12354488) Homepage Journal

    In my opinion, comments are useful -- but literate programming is where it's at if you're looking for the best way to document your code.

    Knuth did a lot of work in the area -- if I remember correctly, all of the sources to TeX are written in a style understood by the "web" literate programming tool.

    There was also a good article by one of the Perl folks (Nathan Torkington? M.J. Dominus? Chromatic? I can't remember.) on POD, and how although POD wasn't literate programming, it was still useful. That article was great in that it showed a middle ground that may be more palatable to your non-LP-fanatic programmer.

    That being said, I prefer full-on LP for large projects.

  • Something i notice (Score:5, Insightful)

    by bmajik ( 96670 ) <matt@mattevans.org> on Tuesday April 26, 2005 @09:19PM (#12354490) Homepage Journal
    i do a lot of code reviews at work and nothing makes me happier than good comments.

    but just putting a bunch of blocks of comments that are like "get customer", "build record", etc are basically useless. If you use programming by intent then its more or less obvious that the code

    GetCustomerFromDatabase(foo)

    is going to do something with a database and get a customer. a comment telling me that is useless.

    what i like to do is write a few paragraphs of text at the top of a function. it explains my general approach, why im doing certain things the way i am, why im not doing other things, and why the function even exists.

    essentially the comments should be enough that anyone that knew the problem space ought to be able to read them and come up with more or less a similar implementation.

    then, in the body of the method anytime i do something that i feel isn't completely obvious, i put a 1 or 2 liner infront of, i.e. "we have to do this because zergs are sensitive"

    the end result of all of this is that code reviews can see what you were thinking at the time the code was written.. and you're documenting assumptions about the problem, the apis, your understanding of the language, etc, all right in the code. it makes finding errors pretty easy.. someone that can't even read source code can read the comments and get an idea of the correctness of your approach.

  • Joel on Software (Score:5, Interesting)

    by TrueJim ( 107565 ) on Tuesday April 26, 2005 @09:24PM (#12354535) Homepage
    "There's a subtle reason that programmers always want to throw away the code and start over. The reason is that they think the old code is a mess. And here is the interesting observation: they are probably wrong. The reason that they think the old code is a mess is because of a cardinal, fundamental law of programming:
    It's harder to read code than to write it."

    From Joel on Software
    http://www.joelonsoftware.com/articles/fog00000000 69.html [joelonsoftware.com]

    Always comment.

  • New Techniques and Better Programmers. (Score:5, Insightful)

    by X-rated Ouroboros ( 526150 ) on Tuesday April 26, 2005 @09:24PM (#12354543) Homepage

    If the comments are clear, a better programmer than you can come along later and say "What the hell was this guy doing?" and then replace your lines of fumbling crap with much cleaner/clearer code.

    It's the difference between being able to see what you were trying to do vs. figuring out what you actually did.

    Call it "Intent Oriented Programming" if you want.

  • They are (Score:4, Insightful)

    by MarkusQ ( 450076 ) on Tuesday April 26, 2005 @09:25PM (#12354549) Journal

    Comments are a maintenence nightmare. They get out of sync with the code, and (especially when the code is bad to begin with) people read them instead of the code.

    That means over time the human's understanding of what the program does starts to diverge from the computer's understanding.

    This is not good.

    If something is too hard to understand the way it is written without comments, it should be rewritten. You will save time in the long run, trust me.

    Remember the old adage: Don't get suckered in by the comments--the bug is in the code.

    --MarkusQ

  • Uhh... (Score:5, Funny)

    by PrimeWaveZ ( 513534 ) on Tuesday April 26, 2005 @09:26PM (#12354557)
    UsngShrtCmtsIsOftNotEnghAsOneMyNdToReWrtShtInTheFt r.

  • The problem isn't lack of comments (Score:5, Insightful)

    by jjoyce ( 4103 ) on Tuesday April 26, 2005 @09:26PM (#12354559)
    The problem is usually functions that are too long and are not orthogonal. Write short, orthogonal functions and you'll see your need for heavy commenting go away along with the need for long variable names.

  • Raskin (Score:5, Informative)

    by kebes ( 861706 ) on Tuesday April 26, 2005 @09:27PM (#12354575) Journal
    JEF RASKIN, professor of computer science at the University of Chicago, is best known for his book, The Humane Interface (Addison-Wesley, 2000), and for having created the Macintosh project at Apple. He holds many interface patents, consults for companies around the world, and is often called upon as a speaker at conferences, seminars, and universities. His current project, The Humane Environment (http://humane.sourceforge.net/home/index.html), is attracting interest in both the computer science and business worlds.

    For those who don't know (which apparently includes whoever is in charge of the linked article), Jef Raskin passed away this february. You can view the official press release, [raskincenter.org] or read more about [wikipedia.org] his contributions to computer science. I don't know when the article was written, but it seems it should mention that Raskin has passed away. In any case, his advice about commenting is good, just as his advice on user-interface design has always been lucid and helpful.

  • Indeed (Score:5, Funny)

    by screwballicus ( 313964 ) on Tuesday April 26, 2005 @09:29PM (#12354591)
    I was recently reading through some code I wrote ages ago and hadn't looked at in years, and wondering...dear god, what's this confused mess trying to do?

    Imagine my relief when I came upon a helpful comment:

    What the hell was I thinking when I wrote this?

    All it took was one comment to put my mind to rest: no, it's not just me being stupid in the present. This code seemed this terrible back then, too.

    Comments save the day once again.

  • Comments Should Reflect Intent (Score:5, Informative)

    by Bob9113 ( 14996 ) on Tuesday April 26, 2005 @09:38PM (#12354659) Homepage
    I found the following in some production code, which quickly and concisely demonstrates why many comments are highly questionable:
    /** Always returns true. */
    public boolean isMagilla() {
    return false;
    }
    That's the core problem with many comments, but it can be avoided. Comments are good when they state the intent or business case for a block of code, acting as a guide to the meaning of a block for subsequent developers. They are bad when they profess to know the actual outcome or implementation of a block; only the code itself can accurately reflect the state of the code.

    The above would be far more useful like this:
    /** Tells whether this instance meets the magilla criteria. */
    public boolean isMagilla() {
    return false; // currently, no MyClass meets the magilla criteria.
    }
    Now the intent of the method is clear, and anyone coming along who wonders why it's hard coded will know under what circumstances they should change it to a formula (namely, if MyClass becomes capable of meeting the Magilla criteria).

    Comments can be good, but they should always be a guidepost to the intent of a block of code, and not attempt to explain how the code achieves that goal.

  • Comment interfaces, not implementations (Score:5, Interesting)

    by bunratty ( 545641 ) on Tuesday April 26, 2005 @09:43PM (#12354692)
    My basic rule of thumb about comments is to comment the interface. In C/C++ this would mean writing the comments at the beginning of all function declarations in .h files instead of .c files, and in Java would mean writing Javadoc comments at the beginning of all methods. The idea is that if you know what a function/method does, you should be able to understand how it does it. The inside of functions/methods should have minimal comments, usually just a one-line comment for each major section explaining what that section does. Sometimes how the function/method works needs to be commented, as in:
    void sort(int arr[]); // sort arr, ascending
    ...
    // Uses quicksort
    void sort(int arr[]) { ... }

    Of course, there are always exceptions. When I was writing low-level code that manipulated hardware registers, I wrote a multi-line comment before each line of bit-fiddling code, complete with what the code did and a cross-reference into the hardware manual. Something like:

    // Set the serial port to big-endian mode
    // See SlurpSCC manual page 3-5
    bitset(slurp->serial, bit(13));

  • Debug code not comments (Score:5, Insightful)

    by iplayfast ( 166447 ) on Tuesday April 26, 2005 @09:46PM (#12354717)
    I find that for simple code that requires little thought, little in the way of comments is required. Sometimes comments just get in the way as the code progresses over time, and the comments don't. It's better to code with long descriptive variable names, and structures then depend on comments.

    For example which would you rather read.

    #define AgentNameLen 41
    #define CustomerNameLen 51

    struct CustomerID
    {
    int CustomerID;
    char AgentName[AgentNameLen];
    char CustomerName[CustomerNameLen];
    };

    or

    struct CoID //Customer ID structure
    {
    int ID; // ID number for the customer
    char AName[41]; // Agent Name
    char CName[51]; // Customer Name
    };

    To me the first is much more clear, and throughout the code will be obvious as to it's use. The second is mildly clear, but will degrade as new things get added to the structure.
    The first also allows things like
    for(int i=0;iAgentNameLen;i++)
    which makes it very clear that you are iterating throught the agent name.

    Algorithm's should be documented, as much as possible, at the top of the function, and any function that takes more then a screen should be looked at to see if it can be broken up into smaller functions.

    (Almost) Always code towards maintainability, never speed. Usually it pays off within the year.

    So to sum up. In order of importance:
    80% code clearly with an eye towards maintainablity
    20% comment

  • The What, the Why, and the How (Score:3, Insightful)

    by wowbagger ( 69688 ) on Tuesday April 26, 2005 @09:59PM (#12354794) Homepage Journal
    There are three things the poor maintainance programmer who has to maintain your code needs to know: The What, the Why, and the How.

    The What: What is this code trying to do. This is where your design documents come in, as they tell what the overall goal of the program is.

    The Why: Why are you doing what you are doing? Why are you writing to this hardware register twice? Why do you divide this value by 1800 here? This is where comments are needed - to explain that the hardware sometimes doesn't take the value on the read, or that the nominal deviation of this signal is 1800 Hz.

    The How: How are you getting the work done. This is where well written code with well chosen variable names comes in.

  • Quality not quantity (Score:5, Interesting)

    by MagikSlinger ( 259969 ) on Tuesday April 26, 2005 @10:03PM (#12354828) Homepage Journal

    Having RTFA, I can see what he's trying to get at, but as someone who has (unfortunately) found himself spending most of my 10 year career in programming cleaning up other people's poop. At first I thought it was because I must have done something wrong that I kept ending up being assigned this work, but as I came to realise, it was because I make the code better than I found it and I have a knack for fixing stuff other people give up on. I also had silly managers who assign work to the people least qualified to do it.

    At any rate, some observations:

    1. 20 lines of comments "documenting" your code before you write it (or even after you write it) is far less useful than writing the code COHERENTLY and CORRECTLY in the first place.

    Last month, I had a 1200 (yes 1,200) line method with huge blocks of documentation before big pieces of code. I still can't quite tell you what it thought it was doing. The code was a for loop wrapping around code to handle 3 different and mutually exclusive situations. Instead of identifying which of the 3 situations it was and creating a method for each situation, the person just stuffed it all in with lots of comments documenting everything the article's author said. The code was still unmaintainable.

    2. Comments are useless unless they are kept up to date

    Part of the reason that code was so difficult to figure out was because most of those big verbose documentation comments referred to a completely different implementation. After the programmer had written the first case, she encountered some other bad cases and eventually had to completely change a block of code embedded in this 1200 line for-loop. The code was now correct, but the comments no longer had anything to do with that block of code.

    3. Don't be clever when you can be clear

    I have made a solemn vow to hunt down and hurt anyone who puts "clever" code in my project. I am so sick of trying to figure out what some obfuscated piece of code in C, C++ or even SmallTalk is doing. And find out it was just a "clever" way of doing something pretty straight forward like iterating over a list. There was no speed gain from the clever trick, and the code wasn't even a bottleneck to begin with. *sigh*

    4. If you don't know how to solve the problem, write some experiment code in a separate app to figure it out. Then take the time to do the "right" thing in the production code.

    3 days from final for a video game. The CD streaming library for the Sony Playstation was making this strange "hic-up" sound at rare moments. By this time, the original author of this code has long since gone to another company. So I plunge into the code and found that the original programmer didn't know how to write streaming code so he created this hack of a hack of a hack of a test (ad nauseum). The code was programmed by accident, not design. No amount of comment before coding could help this. If the author had dumped the code, wrote documentation describing everything he learned then wrote the code, things would have been a lot better.

    5. Unrelated to comments, but use variable names that make sense. Don't name them arbitrarily or to amuse yourself!

    That CD sound streamer code I mentioned above used quirky names for variables. Can you tell what "little_ninja" is supposed to be just from the name? When I confronted the coder about this quirk of his (in another library he wrote), he got all huffy and didn't understand why people didn't appreciate his little puzzles or his sense of humor. It galls me he still earns a paycheck in the industry.

  • What do you guys think of the following code? (Score:5, Insightful)

    by francisew ( 611090 ) on Tuesday April 26, 2005 @10:03PM (#12354838) Homepage

    I kid you not, this is real code my supervisor writes.

    if(preproct(7) >=thres), for j=size(at,2),at(:,j)=at(:,j)-maa;,for i=1:size(at,1),at(i,j)=(at(i,j))/(stda(i)+.0000000 01);,end,end,end

    Note that this is matlab code, where commas are both an end-of-statement indicator (it's also possible to use just a semicolon), and an array index separator. The nice thing about this code, is that I can at least guess where most of the variable names come from. Oh, and there was *no* line break in the original code. Hooray for the avoidance of those wasteful '/n' characters?!?!

    To answer the original poster: yes, comments are of vital importance.

    Then again, if a program is structured right, things can be organized into sections, each of which is then commented, as opposed to a bunch of seemingly random lines with comments spaced throughout. Sometimes the layout of code, in conjunction with good variable names, is the best possible method of commenting it. The one thing comments are good for is to assure that someone not familiar with the particular language being used, will still understand the purpose of the code.

  • Speak, Memory! (Score:3, Interesting)

    by guet ( 525509 ) on Tuesday April 26, 2005 @10:07PM (#12354857)
    program.files.each do | class |

    class.methods.sort.each do | method |

    5.times { method.refactor! unless method.elegant? }

    end

    if problem_domain > current_language
    choices << comp.lang.each
    current_language = choices.best
    project.restart
    evangelise(current_language)
    end

    end

    comments << intentions.remove(implimentation_details)
    puts comments

    def refactor!
    method.split! unless method.size < Too_Big
    method.rename! unless method.name.clear?
    end

    def evangelise(lang)
    slashdot.comment.post
    puts "#{lang} is the only real language"
    end

    goto (1.0/0.0) and $beyond

    http://www.rubygarden.org/ruby?MoviesTheRubyWay

  • You're right, but Raskin is wrong (Score:3, Informative)

    by Univac_1004 ( 643570 ) on Tuesday April 26, 2005 @10:14PM (#12354905) Journal
    Raskin (who did not write code himself, but was more of a essayist) was a devote of "Literate Programming", first promulgated by Knuth: http://www.literateprogramming.com/knuthweb.pdf/ [literateprogramming.com]

    In "Literate Programming" the comments are all important and the code itself is trivialized. The code, as Jef told me, is like "raisons in the muffin of the comments." There are paragraphs of verbiage which might go on about the history of the project, why certain features were discarded, etc., etc, and might not even explain what the following line or two of code was concerned with.

    It's really very difficult to deal with code that has been written in this style ("literatized?" ) since the actual structure of the program is severly obscured. It serves as an example of how overdoing a good thing is usually a bad thing.

    Jef was a nice guy, and I recommend his book, "The Humane Interface" for its many interesting ideas. His attempt to put them into practice in the Archy project http://rchi.raskincenter.org/aboutrchi/index.php/ [raskincenter.org], was not completed before his death. Even for that, Archy is very close to his vision.

    But since Jef was in many ways an extremist, one can demonstrate in Archy his pushing of his concepts to the limit resulted in the end fully maching his goals. Somewhat like "Literate Programming", in fact.

  • There will always be losers (Score:5, Interesting)

    by menace3society ( 768451 ) on Tuesday April 26, 2005 @10:18PM (#12354929)
    There will always be loser "programmers" who write code without comments, or write code without useful comments, or modify usefully-commented code without modifying the comments. Everyone I've seen who's ever put up an example of how code is self-documenting and that comments are just extra text saying the same thing have fallen into the second category. Of course things like "prints a message" or "check to see if i==0" are stupid comments. But that's just a straw man if you want to say that all comments are useless (I dare these people to read uncommented assembly of more than about 40 lines, and tell me the code documents itself).

    The true useful skill lies in reading sloppy and/or wizardly code. Some people think that they have job security if they write impenetrable code, but then they can just be fired and all their code rewritten. If you can read others' "unmaintainable" code, you enable your employer to save money by not having to rewrite everything the guy they just fired wrote. So they'll want to keep you around as they fire/downsize everyone else. I It doesn't really matter what kind of code you write, since you can read whatever. advise everyone to start reading up on the Obfuscated C Contest, and practice figuring out what evertyhing does. Then you can handle any kind of code thrown at you, and the code you actually write becomes of secondary importance.

  • Good comments are good (Score:3, Informative)

    by localman ( 111171 ) on Tuesday April 26, 2005 @10:21PM (#12354947) Homepage
    using short, descriptive variable names 'should' be enough as long as the code is well-organized.

    Definitely not. No matter how clear your code is, it only gives you an idea of what is going on the small scale. You often need comments to describe your big-picture motivation. But the comments have to be good too.

    Here's a classic bad comment:
    // add one to the total
    ++total;
    That's useless. But a comment can help:
    // the total doesn't count the root node of the tree
    // (since there's no actual entry in the DB for node "0"),
    // so we just add that in here...
    ++total;
    No matter how clear you write the code you're not going to get that much understanding without a comment.

    It's just a simple example off the top of my head, but that's how I use comments. The code clarity is all that's needed to tell what you are doing, but comments can tell you why you are doing it. You need both for truly maintainable code.

    Cheers.

  • I learned the hard way (Score:5, Interesting)

    by amigabill ( 146897 ) on Tuesday April 26, 2005 @10:24PM (#12354975)
    My learning experience about commenting code was a difficult one. Like many, while in college I wrote the code and then went back to comment it so the profs were happy.

    Then I did a co-op with an automated storage/retreival systems company in their software department. One of the processes involved in a communications system needed some work. The code was licensed from another company in another country. There was no documentation for this communications system. There was very little commenting in the code. Luckily it wasn't in a foreign language. Unluckily it was wrong, apparently the structure of this program was similar to that of another, which was mostly gutted and rewritten, but a few old-program comments survived to be the ONLY comments in the new program.

    Sure, the sources could be reverse engineered to provide the documentation required. I did it. It took a few weeks.

    After that, I didn't leave comments for last anymore. It's been a good thing. I now work for a semiconductor design company and often write perl scripts or skill-language scripts to automate tedious tasks. I think I'm abou thte only one in the office that comments such scripts in any way. It's nice to read what stuff does when I have to revisit code many months or years later. I hate having to revisit someone else's code because it's nearly guaranteed to be completely barren of anything human-readable.

    Listen up kids! Commenting is GOOD! Your professors aren't just being jerks. Learn the easy way and hopefully save yourself a great deal of trouble with your own code. Other people's code will always suck, but your own shouldn't have to.

  • Literate Programming (with caution) (Score:4, Interesting)

    by os2fan ( 254461 ) on Tuesday April 26, 2005 @11:25PM (#12355452) Homepage

    I have written programs in both raw and literate programming style, i prefer the latter. In fact, i wrote a literate-program pre-processor to write programs, and it made the program easier to write and more bug-free.

    In literate programming, you rely on a pre-processor to make the output production, so you are free to put things together as you want. What this means, is that bracketing code (eg open, close files), can be written in the same block, which are invoked separately.

    The main program then ends up looking like a rough scetch, full of commands to include other bits. With wing comments, it is easy to see what is going on.

    /* A rexx script */
    !inc rexxsets ; standard settings
    !inc cmdopts ; process command line options
    !inc fileopen ; open files
    !inc mainprog; main program
    !inc closefile ; close files
    exit
    !inc subs ; subroutines

    One uses a folding editor to search for strings like "!topic". This will not show you a consolidated index, but you can use it to also show where you're are, and any missing bugs.

    On the main, Jon Bentley's comments on Literate Programming are fair (that is, it creates a good environment for writing single-purpose code), but one needs to consider the context the program is written for.

    The form i use was specifically designed to allow all sorts of text-output, so the same file can make as output, eg .CMD, .REX, .TXT and .HTM output, which means that when you run the script you get a perfectly matched set of files, all correctly pointing to each other.

  • Actual code block (Score:4, Interesting)

    by GrouchoMarx ( 153170 ) on Wednesday April 27, 2005 @12:08AM (#12355754) Homepage
    I love telling this story...

    Last year I had a brief stint at a small software company that had just taken a project in-house that was developed by an outside contractor. My job was to take the code they'd just inherited (which no one there knew anything about) and add some features to it on a tight schedule. Documentation? What documentation?

    The extent of all of the code comments it had was the following (and no, I'm not making this up):

    if(...) {
    break; // break
    }

    If that wasn't bad enough, I knew the original developer personally. She was a former professor of mine and I'd worked for her company only a few months before she had taken that contract.

    As someone who has had to deal with code with descriptive names and no comments or docs to go with them: If you write such code, may you rot in the lowest level of hell along with traitors, used car salesmen, and people who answer cell phones during movies.

  • Purpose of comments (Score:5, Insightful)

    by Todd Knarr ( 15451 ) on Wednesday April 27, 2005 @12:42AM (#12355944) Homepage

    I'd say you're right, comments are more important. Clearly-written code should make how it's doing things obvious, yes. Comments, though, should say what is being done and why it's being done the way it is.

Slashdot Top Deals

If money can't buy happiness, I guess you'll just have to rent it.

Close