Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Stop commenting your code just to say you did

bradt.ca

Post reply on HN
Print view View original

61–70 of 76 posts

Re: Stop commenting your code just to say you did

#61

Post by logfromblammo »

pekk wrote: post #19
logfromblammo wrote: post #16

My current employer makes the useless code comments mandatory. They do not need to make sense or be useful; the requirement is that they exist. Fortunately, they pay me enough that I am not looking for other jobs over it. No, I'm looking elsewhere due to the many other aggravations that are not worth the salary. Not only are businesses training younger developers to do this, but they are training older developers to…

If they were paying you in part to make adequate documentation (which might well include good code comments) I wouldn't see any problem

It is a Cargo Cult Code Convention.

Good code has documentation, therefore our bad code will become good by adding documentation. Truthful comments, such as the following, would likely get the writer fired and not improve the code one little bit.

/* This code block is a crufty, kludgy crock of dung. I have argued several times that it represents a morass of technical debt, security holes, and degraded performance, but I have so far been explicitly denied permission to fix anything in it. In addition, it is so tightly coupled to equally bad code that it is impossible to test easily. But now the good news. If you can stand to look at it, this code will pay your mortgage, and the mortgages of 20 other people, because your bosses have more money than brains. /

Instead of writing that, you get this.

/ Magic. Edit this code at your own peril. */

Re: Stop commenting your code just to say you did

#62

Post by Aardwolf »

jgrahamc wrote: post #36

Leaving comments in real life: http://blog.jgc.org/2011/11/leaving-comments-in-real-life.ht...

From the article: "One day, I suppose, it'll be possible to use an app-for-that, to leave virtual notes."

WHYYYYY? Physical notes are much better! They'll be there forever, while the app would be a temporary fad.

Re: Stop commenting your code just to say you did

#63

Post by millstone »

whyme wrote: post #33

I'll suggest there's a missing ingredient here...I found I was able to eliminate many of my comments by asking myself if that someone whom might read my code would be better served with a unit test instead. I also found, however, that this needs to lead to an understanding that unit test are in fact a form of documentation and should be treated as such.

It's a great point that, if there's some behavior worth capturing in a comment, you may also want to capture it in a unit test.

But why should you strive for the "ability to eliminate" comments? What is the advantage of having fewer comments?

Re: Stop commenting your code just to say you did

#64

Post by fournm »

quackerhacker wrote: post #26

Comments in production code have always been a pet peeve of mine. I understand the OP's frustration on useless comments where the function clearly states enough in it's naming convention. I brought this up to one of my instructors before and he said that comment overhead is negligeble on bandwidth (I was referring to css and js commenting at the time), but I don't think that's true when you factor in mobile networks…

I would hope that you would be using minify in some way, which lets you still have your comments and just drop them for production.

Re: Stop commenting your code just to say you did

#65

Post by methodover »

I cannot recall a time in my career as a programmer where the inclusion of a comment has caused me serious problems.

However, I can recall many, many times where I've read code that does something odd, and wished that there was some documentation explaining it.

I've met many programmers who rarely comment and make points similar to those made in this article. It's an easy argument: code should be self-documenting. But I've seen too many programmers jump from "code should be self-documenting" to "I shall never use comments/docstrings."

I feel like the problems outlined in the article are overstated. It really isn't a big deal when you read a comment that doesn't make sense, or is empty of content. It's a much bigger deal when you read strange code which really deserves documentation but there is no documentation.

Re: Stop commenting your code just to say you did

#66

Post by IgorPartola »

lhnz wrote: post #49
swanson wrote: post #24

Earlier quoted context omitted.

// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

// Hardware acceleration should be switched off. // Originally we'd planned to use hardware acceleration but later // on in the project's life cycle we were told we needed to support older // versions of Foo: X and Y. This caused some bugs documented [here](#123) and [here](#234) // due to incomplete support of feature Z and the way that [internMethod()](#internMethod) is currently implemented. // @TODO: It would be…

Let's look at some stylized comments I've seen over the years:

    // Add tax
    total = price + tax
Useless comment, isn't it?

    // Iterate over the order items
    for item in order:
        ...
Also useless.

    for ($i = 0; $i
Not as useless as the code below it, but still pretty useless.

    def add_item(order, item):
        '''Appends item to order.

        param order : instance of 
        param item : instance of 
        return : None
        ''''

        order.append(item)
This is a great example of a useless docstring. The developer might as well have put the code into the docstring.

    # 
    # The code below uses an undocumented API, that nonetheless we must use in order to make the code work.
    # As per  and , this is a known issue.
    # We may be able to remove it after release X.Y where the upstream fixes it.
    
    Widget._enableDitzelMode(Widget._DITZEL_MODE_FLAG_X)

    #
This is not only useful, but more or less required. If you do any kind of monkey patching, please add this.

    # 
    # The code below looks wrong, but is in fact correct. This @#$%ing API makes you say "true"
    # when you mean "false". Do not alter without reading .
    # Set PRODUCTION mode to ON.

    Widget.setStagingMode(true)

    #
This is also pretty much required, I think.

    // Make sure to use === below since foo can be null OR '' which mean different things for us:
    if (foo === null) {
        alert("Value is unknown.");
    }
    else {
        processValue(foo);
    }
I'd say also useful, but the code is going to change eventually.

Re: Stop commenting your code just to say you did

#68

Post by CodeMage »

carsongross wrote: post #7

God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.

You're completely right, there is no sense in pointing out what kinds of comments detract from readability and anyone writing about that is a smug jerk.

All sarcasm aside, there's nothing wrong in getting your thoughts together in comments before you actually write code. What the author objects to -- and I agree with that objection wholeheartedly -- is leaving those comments in your code once you're done coding.

Other comments describe and discuss the dangers and downsides of leaving the "what" and "how" comments, so I won't go there. Instead, I'd like to propose a habit to establish when writing code: when you're done coding, remove all the "what" and "how" comments and try to read the code. If you can leave it overnight before trying to read it, even better. If it still looks easy to understand without those comments, then there's a chance it might be good enough for other people. Otherwise, do whatever you can to make it more understandable -- break it up into smaller methods with descriptive names, for example.

The point I'm trying to make is that there are two kinds of WTFs I get when I'm trying to read code: the "why the hell did they do this" WTF and the "what the hell does this do" WTF. The former is the kind of WTF you have to solve with comments, because no amount of comments is going to explain why you've done things this way, whereas the latter should be solved by writing more readable code.

Re: Stop commenting your code just to say you did

#69

Post by whyme »

millstone wrote: post #63
whyme wrote: post #33

I'll suggest there's a missing ingredient here...I found I was able to eliminate many of my comments by asking myself if that someone whom might read my code would be better served with a unit test instead. I also found, however, that this needs to lead to an understanding that unit test are in fact a form of documentation and should be treated as such.

It's a great point that, if there's some behavior worth capturing in a comment, you may also want to capture it in a unit test. But why should you strive for the "ability to eliminate" comments? What is the advantage of having fewer comments?

I subscribe to the minimalism approach. i.e. I do my best to improve the signal to noise ratio (which is inline with the authors goal).

Also, in many cases, having a both the unit test and the comment is a redundancy.

Re: Stop commenting your code just to say you did

#70

Post by overcyn »

wdewind wrote: post #54
fournm wrote: post #11

Earlier quoted context omitted.

This isn't always possible in every case--it's not too hard to imagine a lot of trivial assignment all going on at once, that isn't immediately obvious what it is or why on earth it exists. //really bad example, just something really repetitive function main() // set up month boundaries janStart = blah; janEnd = blah; // ... decStart = blah; decEnd = blah; end where it's not too hard to imagine many languages without…

Return an array or hash?

Or just write a comment...
Post reply on HN