Don't comment your code | Hacker News Reader

Don't comment your code

version2beta.com

I don't like to strenuously object anything in general, but I'll make an exception this time: this advice makes me burst a vessel every time I hear it, because I must confess that the number of code bases I've seen that are chronically over-commented with incorrect information that do more harm than good approach zero. Most commonly, I think this sentiment is partially wishful thinking, partially frustration of incorrect documentation, and partially with code that is more convoluted than otherwise ideally realized (submit the patch, if one can).

Such pleas are always accompanied by some example in a vacuum which requires no justification for why a piece of code exists, including tricky branches that required careful reasoning to catch corner cases that might go without detection when breezing through doing maintenance or changing things. If nothing else, comments provide a nice breathing space between even short chapters of a function to help the eye track the code...much better than cramming stuff into a symbol name and relying on guesswork.

Does this mean that the post contains bad information? No, not necessarily, but for me, the headline and thesis do not follow from the otherwise reasonable techniques detailed.

First of all, if comments lie, so do function names. So refactoring to replace all your comments with function-names is a waste of time. The same goes for variable names; the difference is that you were presumably going to have variables in your code anyway.

More constructive commenting advice:

If your comments are supposed to explain what the code does, give a few extra minutes to considering whether the code could be clearer (some tasks might require complicated code that merits comments, but most tasks can be accomplished with self-explanatory code).

On the other hand, sometimes there are external reasons, not enscapulated within your code, why you must do something surprising. This unequivocally merits comments. "I did this because of RFC #XYZ" or "Partner FooCorp needs this bizarre format, see /global/path/to/spec", or "our data has such-and-such a distribution, thus this surprising approach, which improves the 99th %ile latency".

Not only that, but in the last example in that section he replaces a fairly short and readable expression with a function call. I don't see how this is different than a comment in any meaningful way (except that it requires extra lines of boilerplate and whitespace that don't lift any explanatory weight), and unlike a comment it pollutes the call stack for no good reason.

The call stack is cheap, its your mental stack that you should be trying to optimize for. Any label over a set of operations (even a single expression) will reduce the mental load necessary to understand an operation, assuming its reasonably named. Managing a stack is what computers are good at. Lets optimize our code for how we can better comprehend it--at a consistent level of abstraction with the fewest amount of level changes as possible.

Oh, I wasn't trying to make a claim that this would result in any noticeable performance degradation in the vast majority of cases, but as a means of making code more understandable this particular example suffers in comparison to a comment: less code is on the screen, it requires the reader's eye to jump elsewhere, and again that particular expression is simple and about as easily understood as the function name that replaced it. I think we agree on what to prioritize in writing code, but I don't think that example in the article was a good demonstration of those priorities in practice.

>First of all, if comments lie, so do function names. So refactoring to replace all your comments with function-names is a waste of time

This isn't my experience at all. Comments don't need to be read, therefore the programmer has a greater chance of not realizing they are now out of sync with the code (this can happen on a project you're completely familiar with). Function and variable names must be read and comprehended to use, so it is much more likely that any divergence will be picked up. I completely agree with the author that descriptive function and variable names are much more valuable than comments, and thus the former should be heavily favored.

Or, you know, learn to write useful comments already. I know it's hard, but doable, really.

Exactly this. Don't litter your code with comments, use them when they make sense. For example, if you're doing something "against the grain" but have a good reason: leave a comment explaining why.

I quite liked the previous article we had "Comments are apologies" or something. HN seemed to rail against it overall, but it makes sense to me. It's sort of "Sorry, but this has to be this way because API <x> does thing <y>". Or "This is a bit convoluted, but necessary because the naive way is too slow." That doesn't have to be the literal text of the comments, but that's the sort of mindset they should be written in, imo.

I'm curious: Have people had a look at code they wrote ten years ago? Are they glad it was uncommented, or would they have preferred comments, or were the comments lousy?

When you're taking on someone else's project do comments help, or do they make things more confusing?

Well, I'm only 23 so any code I wrote ten years ago was hopelessly simple by comparison to what I'm writing today. But to answer your question: In general I found it over-commented, but it was simple enough that I could ignore the comments and look at the code. I don't know how I'd feel looking back at my code now.

The rule was originally against comments of the kind:

    eggs:=eggs+1; (* increment eggs *)

All the other comments should be kept, and maitained synchronized with the code.

Now like you may want to have some tools to track the link between requirements, design and code (so that when requirements change you may know what design decisions should be reviews and what parts of the code should evolve, youl may want some tools to track the dependency between the code and the comments and check their updated at the same time.

So I would suggest, instead of throwing the baby with the bathwater, to imagine and implement the missing tools!

Reply on news.ycombinator.com