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

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: