Hacker News Reader

Comment by sydd | Hacker News Reader

> Code comments? Nah.

This is one of my biggest gripes. Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases. Yeah, you don't need to document the convertMinsToSecs() method, but most real life codebases are full with edge cases, shortcuts, temporary solutions, half-complete reorganizations. So people use this for writing no comments at all, whereas a few words of comments would save hours of investigative work for future developers working on the codebase.

View on HN

> Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases

Agreed. For example, comments about Why-do-this, and Why-Not-do-that can be necessary, even if the code shows what happens.

Imagine you're in a taxi, and it suddenly takes the wrong turn, now instead heading towards Surprise-City. Then — you know what is happening. You're going to Surprise-City.

But would't you also want to know Why?

So then it's nice if the taxi driver explains Why: "I buy milk to kitten."

I think the 'Linux kernel coding style' explains comments pretty well:

https://www.kernel.org/doc/html/v4.10/process/coding-style.h...

my priority for comments is that they should answer "why?" and "why not?" questions. Why does the method/function do it this way? Why didn't it choose that other, perhaps more obvious route?

That's not necessary in every case. But it's true in a good number of them. The code alone can never tell you that - but it's often invaluable during evolution/refactoring.

Why does this code exist?

What are you working around?

What are the assumptions? What limitations?

If it's complicated enough that I'm only understanding it because of the context of the last week, we need the comments. Anything that can speed the reverse engineering in 6 months when it breaks is helpful, because then you can quickly decide that we got different input or if we missed an edge case or whatever.

Yah, and what's gross is when your team-mates criticize you for leaving comments at all. Let alone a lengthy discussion on why.

While I agree to some extent, the problem with comments is that they need to be maintained in order to be helpful: code comments - updated when the code changes, general comments - when the context changes, etc. This is a work in itself: developer has to remember to do it, reviewer has to remember to look for it. In my experience, people tend to forget to do it or just don't bother, which means that someone else finds himself with a contradictory, outdated, confusing comment further down the road.

Sure but which is more likely:

Someone updating the comments in code that they are updating because they see the comments right in front of them.

Someone going to look through the documentation to see if there is anything relevant about the code they are working on that needs to be updated.

Somewhat surprisingly, it depends. For instance, in our case application support is responsible for/interested in the documentation, and they make sure that developers create/update the relevant documentation for each of the release items. Stale comments, on the other hand, need to be identified and addressed in code reviews, and in practice we're not always good at that.

I'm really grateful for my current team because of this.

It takes 5 minutes to have thoughtful naming and "this is why because..."

They have done a stellar job at that.

> good code is self-documenting

I still believe this to be more or less true.

The important part there is that you have to write good code though.

So, the advice is bad, as most people (including myself, no doubt), will write mediocre code, just by the shape of the distribution (assuming it's normally distributed, which is a strong assumption, but without data it's probably reasonable).

Advice that relies on people caring about their craft/having the skills to do the work well doesn't scale, so it's bad advice where those things aren't true.

Also in lots of cases you are in a hurry to meet that deadline that compromises code quality. Better to leave a comment in this case than nothing

Yeah, especially if you do something weird. People have often done weird strange stuff that made sense when I finally figured out the reason.

Time pressure (and particularly with contractors) can lead to some horrific long-term burdens of maintenance.

You come a long way with avoiding direct calls in "if" clauses and similar, using descriptive variable names, and not trying to be clever for the sake of being clever.

For example, instead of

    if (order.version > 1) ...

assign it to a descriptive variable

    bool orderHasChanged = (order.version > 1);
    
    if (orderHasChanged) ...

IMO this makes it much faster to read and understand, because it says something about the intent. It can also be easier to spot bugs.

It's a bit more to write, but I find it makes a big difference when coming back to the code later on, and typing is usually not the limiting factor when writing code.

I think Uncle Bob got cancelled /s, but politics aside, I don't think he was necessarily wrong about good code documenting itself, but it came with a lot of direction about what then exactly constitutes good code. If people don't bother to hone the skills of good types and methods, well named and with clear responsibilities, of course they're not clearing the bar to drop the comments. Having grown more senior, I believe I have gotten a little better at expressing meaning and intent through the code itself, and I'm surely writing a lot less comments because of it, which seems a win overall.

Reply on news.ycombinator.com