• Wongo (unregistered) in reply to Anonymous Coward
    Anonymous Coward:
    No. It shows that you are have been thinking about the process before you have begun writing it.

    // I'm thinking about writing some code. // Maybe a loop. // Yes, a loop is a good idea. // I need some sort of variable to hold the index. // I'll call it "N". // The loop will increment this index variable on each iteration. // OK, I'm going to write the actual code now. // Oh, wait! // There's something wrong here... // The index of the loop is an integer value (it means that there are no decimals). // So I'd rather call it "I", to serve as a reminder of this fact, and facilitate the understanding of the code without the need for a further comment on the integer nature of that variable // Now to the actual code FOR N = 1 TO 10 // TODO : consider trying to code directly // ...

  • nigenet (unregistered) in reply to fourchan
    fourchan:
    This is how it should be:

    // Increment i by one, because i needs to be incremeted by one here i=i+1;

    Nooo...

    // Increment i by one, because i needs to be incremeted by one here j=i+1; i=j; // ;-)

  • Candy (unregistered) in reply to tmj

    This reads: I can't code.

    How about writing your code, if it should do this, like so:

    DoA();
DoB();
return Z();

    and then writing the functions to make this work?

    Why do you insist on writing a clear spec of what your code should look like, then to mangle it into oblivion? Just make readable code already.

  • (cs)

    I dunno... maybe I'm just rationalizing because a good portion of my own comments fit this scheme, but I find this style quite useful when I need to make changes.

    It's not the "how", it's not the "why", it's the where that matters when I'm in a hurry. I'm able to scan through comments like the example provided and follow the flow to quickly find where to insert/remove functionality, bug-hunt, etc. and I'm not even familiar with the code.

    An example that seems pointless in an HTML document:

    <!-- maincontent -->

    
...

    Someone is eventually going to read that, think "well, no SHIT!", and forward it to be ridiculed here. But faced with a mass of nested HTML tags I can locate things much more quickly by scanning the comments than the id attribs.

  • Kawazoe (unregistered)

    We learn to do that in college! The idea is that teachers are trying to give points from comments in code. But they always says : "Not enough comment" like there should have more comment than code.

    Here's some example that occur frequently :

    • No comment on what a class method like "convert(int from, double to)" make you loose points.
    • No comment on a "big" bunch of code making an obvious result like reading from a binary file, registry or a xml file will make you loose points.
    • No comment on language specifics that the teacher don't know (C++ template for instance) or calls to the C++ STL library (like string! or vector!) will make you loose points
    • Oh My God! I don't even want to talk about Boost or any other library.

    The result is this... we learn that we need to say how and not why since why generally produce fewer comments.

    There's two hidden WTF in there. First : some teachers are older than one of my grand-mother. And second : Our computers are so hold that Visual Studio 2008 hang the computer for 5 minutes when you create a new MFC project. (Hint, on my laptop, it take 10 seconds.) Ho yea.... I forgot... it they first session in VS2k8... they where still using VC++ 6 (1998) that can't even process for loops correctly...

  • Joe (unregistered)

    I have to WTF your article here pal. In Steve McConnel's book Code Complete he talks about programming this way, writing out what you are going to do then actually codding once you've got it right. Um, again, the title is "Code Complete". Pick up a copy and read it.

  • (cs) in reply to Anon
    Anon:
    Jimbobzo:
    The problem I have with too many comments is that people change the code, but they dont update the comments,. This leads to comments saying one thing, with code doing another, and actually hindering your code.

    Now that's a legitimate complaint for this style of commenting. You'd hate to see something like this:

    // Add one to x x--;

    Personally, I LOVE seeing code like that. It tells you instantly and obviously what went wrong. If the rest of the comments describe pseudo code, and that logic relies on x being incremented, then obviously x-- is an error.

    The flipside is that if the code changes, then obviously the comments should change as well to reflect it.

  • Ian (unregistered)

    Ok, so he writes English and then translates, line by line, into the programming language du jour. Code Complete actually recommends this practice as a bug-prevention measure. It separates thinking about the solution from thinking about the fairly arbitrary language in which the solution must be expressed. Not that Code Complete is automatically an authority, but it's likely written to turn majority grunt programmers into something at least a little better.

    As to the question of why the code was even written in the first place? Well, are there context clues? Did the author expect that a call graph would be generated? Perhaps this is the result of top-down design with intention-revealing names?

    In any event, I'm much happier that the author at least tried to document the code. And this way, a bug is obviously present when code and comment disagree. You may not know which is in error, but you know to go find out.

Leave a comment on “The How, Not the Why”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article