Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I take it you've never written code that someone else had to call into or maintain. You're basically arguing against documentation or explanation of any sort. Also, I assume you program in straight-up English -- all checked by the compiler -- or else some programming language of the future whose contours match the shape of thought and in which there is never any impedance mismatch between what you are trying to achieve and what you must instruct the computer to do.

And please don't say, "That's right, Haskell" or "Yes, my favorite LISP."



No, they're arguing for documentation of intent rather than documentation of what the program does. What the program does is obvious if you have reasonably decent abstractions; what you intend to do is not so obvious.

    // Increase the counter by one
    counter++;
vs

    // Log that a user has viewed the page
    counter++;
and in fact all that vs

    fn logHasViewed() {
        pageViewCounter++;
    }
    
    logHasViewed();


Exactly. To me, even a comment expressing intent is usually a code smell unless it is in a function header. If the block of code is non-obvious enough that it needs an explanation, it should be its own named function, and the function name should describe its purpose.

Of course these are all SHOULDs and not MUSTs. There are always exceptions. But the general rule is definitely that comments are signals that something is broken.


It must depend on what programming culture you find yourself in, but I've seen more undercommenters than overcommenters, often with the excuse that the code is "obvious" or the comment would be literal.

Sometimes literal comments tell you things that you wouldn't pick up skimming the code: for(var i=0;i<length-1;i++) // skip the last element

Or, a comment could give a reason, like "iterate backwards because..."

Sometimes it takes half an hour to work what what two concise lines of code should say -- there may be something tricky going on, or you may be working around a bug in a driver or library or something -- and you should record what you were thinking.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: