Hacker News Reader

Hacker News

Comment by nikster | Hacker News Reader

Parent Full thread

nikster

Yeah well...

Great code needs no comments.

Bad code needs lots of comments.

I've seen examples of both recently.

I randomly met a guy who told me of his idea to implement a UX framework with windows, buttons, views, etc in python.

A week later he sends me the finished framework. And it's perfect. It's easy to understand, all the names of things make sense, it's orthogonal. Not a single comment anywhere, but perfectly clear. Great code basically.

And there's a project I am maintaining where some parts of the code are pretty much impossible to understand, full of duplicated code - somebody loved copy&paste - duplicated method and class names, and threads going off in all directions. There is a comment for every line of code but despite the fact that I consider myself pretty good at reading other people's code, I am not touching that thing with a 10 foot pole.

My goal is to write code that doesn't require a lot of comments.

View on HN

Great code needs no comments.

Sure it does.

« The simple and obvious way to do this misses important edge cases X, Y and Z. »

« This is to work around a bug in the framework we're using; see http://... . »

« This is deliberately wrong, for compatibility with ABC system. »

> Great code needs no comments.

Great code implementing a particular algorithm for a particular reason might want a comment (1) identifying the algorithm and providing a reference to a published description, and (2) identifying the reason the algorithm was chosen.

Great code that is clear and readable and well-fit to purpose can still, very often, benefit from comments. Not everything that might want to be made clear to readers of code can be expressed in the code.

    > Great code needs no comments.

The most valuable comments that code can't obviate are comments that explain why the code was written this way, the intent, and a summary of how the code fits into the overall picture -- maybe at least a file-level comment.

I think declaring intent is the most valuable comment. What was the author going for with this function? Why is there a nil-guard here when the database column is `NOT NULL`? Is there an actual edge-case or is our data bad or was the author just being arbitrarily defensive against a boogeyman nil?

When reading other people's code, I've found that most of my time is spent figuring out not what the code does, but rather the author's goals and their higher level game plan.

While I do agree to some extent that great code doesn't need any comments, it raises some questions. How can one be sure at the time of writing that the code is easy enough to understand for others? I'm sure that it's understandable for the author, who's been staring at it for a few hours, but will the same hold for a future maintainer?

I agree with other commentators that with comments one can at least express the intent and reasons for particular decisions.

And on a side note, it's wonderful to strive to write great code, but I believe it's easy to misjudge and think "Oh, I clearly write understandable code, thus I'll skip comments" even when it's not that clear. That certainly has happened to me, very likely to others at some point as well.

Sorry, I downvoted this. Great code doesn't need no comments. Lots of comments is definitely a code smell, but anything of reasonable cognitive complexity will almost certainly require some comments.

I can't be certain about your first example, but writing a UX framework is a pretty straightforward thing in terms of what it needs to do, so there probably wouldn't be much need to comment about what it's doing. Why, though - that's a whole 'nother question. Surely it's missing some of those whys.

Reply on news.ycombinator.com