No Comment

There seems to be a push towards not commenting code, with the general argument being that if your code needs commenting, it is too complex. I kind of agree with the sentiment here, code that is tough to comprehend is bad, but I think this is an oversimplification.

In my experience, at the point at which we are writing the code, we are terrible judges about what is too complex. Things we think we will be obvious to anyone [including the new person, straight out of uni] reading through the code turn out not to be obvious, not even to us – six months later when we are trying to track down the cause of a bug in said code.

There is a secondary argument, that comments are not always accurate, because…

The author of the comments has described the intended functionality of the code, but this differs from what it actually does.
The comments may not accurately describe what the code *is* doing, but they might neatly explain what the developer *intended* for it to do and that could be very useful information when you are searching for that oh so elusive bug.

The comments have not been maintained in line with the code and are now stale.
People don’t always do the right thing because reasons. Expect the bullshit but never accept it. Do code reviews; include the comments in the review.

If you find yourself writing comments like “Increment counter”, you should stop. If you have contrived to produce some horribly obfuscated, overly templated, pointlessly typedef’d hell that requires a comment the length of War and Peace to justify, you should be stopped. But if all you want to do is try and give a helping hand to the next person, get to it. :)

I am still learning. I hope to carry on learning forever. I might well be wrong about all or some of these things. I might change my mind on them in the light of more experience, or different arguments. I am totally okay with this.

3 thoughts on “No Comment

  1. Your blog is currently included on our Actually Autistic Blogs List (anautismobserver.wordpress.com). Please personalize your blog’s description by selecting “About the list/How do you want your blog listed?” from the top menu on that site.
    Thank you.
    Judy (An Autism Observer)

  2. JoJo, your blog is currently included on our Actually Autistic Blogs List (anautismobserver.wordpress.com). Please click on the “How do you want your blog listed?” link at the top of that site to customize your blog’s description.
    Thank you.
    Judy (An Autism Observer)

Leave a Reply

Your email address will not be published. Required fields are marked *