Hacker News Reader

Comment by abc-1 | Hacker News Reader

I do all of the above. Summary comments are incredibly helpful and have been validated by empirical research. Too bad many have drunk deeply from the Clean Code koolaid and can’t be saved.

View on HN

I got some flak at a prior job for saying I had some quibbles with clean code (a few years after I had read it), and I'm glad this opinion is more popular today. There's so much cargo culting hype with "best practices" and style, I hate it. Same with how overly dogmatic people were with OOP paradigms when it came out (remember using anonymous interfaces to pass a function around in java?). Same with the functional backlash to that.

It's fun and enlightening to go ham on any particular style/framework/philosophy, but actually living by dogma in prod gets kinda dangerous and imo is counter to the role of a senior+ engineer

The very term "best practice" is such a loaded term. It implies:

1) empirical measurement compared to a large number of alternatives ... the empirical measurement or study is never mentioned: because they do not exist

2) the best practice is valid in all measurements and criteria of comparison: performance, elegance, simplicity, correctness

3) since there is no data, the reasons for why the practice was designated best are rarely even explained

4) nor are the circumstances or individual or source of "best practice" detailed

5) it will always be the best practice: it is the BEST! It CANNOT be improved.

So we have an unsubstantiated, unargued, unsourced, non-authoritative, exaggerated declaration in virtually every case of "best practice"

Copy that. CC has done a lot of harm in some ways.

I was taught to not leave comments in finished code.

I have regretted following that lesson ever since.

If code were ever finished, then perhaps this would make sense :)

Who taught you that!?

I was specifically taught that good, readable code could explain itself; that it would make comments redundant.

Therefore, comments should only be used for things like psuedocode, or as help for fellow developers during dev.

Then, they should be removed once the code is done.

But yea, not a good idea.

This is an example of taking something that is contextually good advise, applying it to all situations, which turns it into bad advise.

If you can make your code more clear, so that comments aren't necessary to explain what it does or how it works, that is probably (but not always!) something you should do. But that doesn't mean you shouldn't have comments. At the very least there should be comments explaining why (or why not) things were done a certain way.

I have almost never run into a situation where a comment was better than a well named function or variable.

It happens occasionally, but it's usually a sign that I'm doing something wrong.

This is fine. A problem arises when you assume that this will always be the case, for all developers, and then mandate that they omit comments, _without checking if your assumption is true for their case_.

IMHO that rule can be generalized: Whenever you make rules for other devs, make sure that the assumptions on which those rules are based are true, lest you interfere with their work in a negative way.

There are indeed those situations where a comment would not increase the clarity of the code.

But one shouls be careful not to mentally think of this as a zero sum dichtomy, where you either have well named functions XOR you have comments, because in reality choosingn both is often the golden path to success.

The danger is of course that code that is totally obvious to you now will take far more time to become as obvious later, be it to your future self or to your psychopathic lunatic co-worker who knows where you live.

So very often code can be made more readable by adding comments, even if it is just saying the same thing with other words, just by reducing ambiguity. Comments can also bridge higher level concepts in a good way, e.g. by you explaining in a few lines how a component fits into a concept that is spread out over multiple files etc.

In the end code is text and like regular prosaic text you can both make it harder to understand by not mentioning things or by mentioning too many or the wrong things. This is why it is not irrelevant for programmers to be good and empathic communicators. Sure in the end readability doesn't matter to the computer, but it certainly matters to all people involved.

well-named works great while you're writing the code. come back to it in a few years, or hand it over to somebody new, and you would realise that what looks like a good name to you means nothing to somebody else.

A line of code can tell you what it does but not why. Unless you are on a newish codebase, you will likely need comments to explain why certain decisions were made

Really? There's a perfectly good example in the article.

    RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs()

That's a horrible way to name a function. Function names should be short, punchy, and unambiguous. They should create a simplified abstract narrative, and all the details should be put into the docstring, so that they can be easily accessible without having to (a) be squashed into an identifier, or (b) be repeated every time you want to call the function.

That is like saying: "A perfectly good road needs no road markings". The point of of good comments is that they make the code faster to read and less ambigous. While good code should indeed already be readable and unambiguos, I have rarely seen code that couldn't be made even easier to understand and faster to parse by writing the appropriate comment.

But of course you will have some individuals who think it is cooler not to, and they are probably the same people who think use after free bugs can be avoided by the shere willpower of the solo-male-genius that they are.

Code explains the what but not the why. And even then, the what might not be so clearly obvious.

This is one of those blindspots devs have in that they believe their code to be good and obvious to everyone but in reality it is not even good and obvious to their future selves who will be the ones maintaining that code

> I was specifically taught that good, readable code could explain itself; that it would make comments redundant.

Good readable code removes the need for comments about what the code does, if the working of the code needs extra explanation then perhaps it is being too clever or overly terse, but there are other classes of comment that the code simply explaining itself can't cover.

Some of my comments cover why the code does what it does, perhaps linking it to a bigger picture. That could be as simple as a link to work ticket(s) which contain (or link to) all the pertinent details, though I prefer to include a few words of explanation too in case the code is separated from whatever system those work items are logged in.

Many comments state why things were not done another way. This can be very similar to “why the code does what it does” but can be more helpful for someone (perhaps your future self) who comes along later thinking about refactoring. These can be negative notes (“considered doing X instead, but that wouldn't work because Y or interaction with Z” – if Y and Z become irrelevant that future coder can consider the alternative, if not you've saved them some time and/or aided their understanding of the bigger picture), helpful notes for future improvement (“X would be more efficient, but more complex and we don't have time to properly test the refactor ATM” or “X would be more efficient but for current use patterns the difference would be too small to warrant spending the time” – the “but” parts are not always stated as they are usually pretty obvious). A comment can also highlight what was intended as a temporary solution to mitigate external problems (“extra work here to account for X not being trapped by Y, consider removing this once that external problem is fixed” or “because X should accept Y from us but currently doesn't”).

IF the code is self-explanatory, then the comments are redundant, and is ok to delete them. But from time to time, there are things that are at least not so obvious in the code. Then is good to leave a comment.

That could be used to see how good a language is for specific tasks. If you need to write lots of comments, maybe you have the wrong language.

I had a professor in college who would grade you down if there were any comments in your code.

Perhaps professor was fed up with over-commenting (comments made up a large part of submitted code), especially if comments were like in https://news.ycombinator.com/item?id=41506466. Unless the course is "practical software engineering" or similar, that good programming practices are a focus, and if the why/why-not parts can contribute to better assessment, an associated paper can be asked.

Sounds like a concrete example of the phrase “Those that can, do. Those that can't (try to) teach.” Far from true for all teachers, of course.

That and “those who actually use power are likely to be those who shouldn't have been given it”!

I have regretted when you fail to follow that lesson.

I did a survey once in about 3/4 of the comments were either wrong or useless. Examples:

//Add 1 to x

x+=1;

//Add 1 to x

x+=2;

//Seconds per normal day

x = 86400;

"Why not" comments are incredibly valuable except they suffer from explanatory decay as much as other comments.

The hope behind Intention Revealing Names is that the dissonance will be too great for the subsequent developers to ignore when they change the code.

Of course, that isn't always true.

An outdated comment is at least a very strong signal that the code might be wrong

And, you definitely had little experience with under-documented code

For me the quality of comments, somewhat based on the metrics that @renhanxue mentions, is a code smell. If code is poorly commented (by my standards) then I treat the actual code with suspicion.

> An outdated comment is at least a very strong signal

Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.

  x = 86400

If I were forced not to write comments, I'd write that as

  x = 24 * 60 * 60

and let the compiler optimize that.

When writing it inline, I like this approach. I like even better when these things have names. Something like `std.time.s_per_day` or `time_utils.s_per_day`. Then in the one place they're defined, use a pattern like the above to make them easy to reason about.

One step further:

    DAY_IN_SECONDS = 24 * 60 * 60

SECONDS_PER_MINUTE = 60;

MINUTES_PER_HOUR = 60;

HOURS_PER_DAY = 24;

DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

> DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

Naah.

DAYS_PER_SECOND = 1 / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY) ;

> I did a survey once in about 3/4 of the comments were either wrong or useless.

> Examples:

> //Add 1 to x

> x+=1;

If 3/4ths of comments are like this, maybe show a sampling of public source code (e.g. from github) that shows how prevalent comments like this are in any real codebase.

I've been programming since 1982 and have never seen this type of "add 1 to x" comment in real code, outside chapter 1 of some intro to programming book.

I once came to a complicated, multi threaded C++ program and saw:

   using namespace std; // using namespace standard

I'm working RIGHT NOW in a codebase where before each function definition there is a comment "// Function"

I wonder if that's intended for a specific workflow, e.g. ctrl-f "Function" enter-enter-enter-enter to cycle through all the functions in the file.

That's the only reason I can think of for writing those comments.

With a half decent IDE you do not need it. It is inexcusable.

Oh I agree, but the person who put them there must have had some sort of reason, even if it's a bad one.

> With a half decent IDE you do not need it.

I agree.

> It is inexcusable.

I think it can be quite easily excused on grounds of triviality, though whether that's appropriate may depend on context.

I would write that comment if it was a long enough list of single line var assignments with enough complex ones that each have a comment like this one.

I will als name each db table column in the correct order by its correct name right above that what decided the value.

// id

user_id = getUserId();

They serve as dividers.

Code is never finished, only abandoned.

If you're commenting out code, don't

If you're commenting about the code, do.

There's a huge difference in the value between one or the other.

> If you're commenting out code, don't

Sure, I'll absolutely stop doing that...

As soon as we get git on our dev server.

What's stopping you from installing it?

I'm not the server admin. I don't even know who is. Ours is not to ask why, ours is but...

Yes I write comments like a maniac. Long doc strings that are informally written. It’s more important for me to say what I need someone else (or future me) to know about a function and its context than it is for me to have some beautiful, sterile 300-line autogenerated soulless docstrings.

Yes, we should all be kinder to both others and to future me (you). Do we know who will be maintaining this code? Obi-Wan meme: Of course I know him. He's me!

I write detailed git commit messages like a maniac.

Git commit messages are better than comments, because they tag the specific baseline of code where a decision was made, and you can write multiple paragraphs to explain something (including all the "why not"), without cluttering the program text.

The problem with comments is that they also pertain to a revision that existed around the time they were written, but they stick around, pointing to newer revisions, perhaps falsely. They add clutter. Unless you use a folding editor, comments can separate pieces of code so that you see a smaller window of the program.

One line of code can be touched by many, many commits. Each of those commits should have something to say about that, and all that talk cannot possibly be put into a giant, ever-growing comment next to that line of code. In regard to my previous point, a lot of that talk won't even be relevant to the current version of that line!

I've taken the view that the thing I'm developing is a git repo, not the source tree.

A source tarball is just something for building and deploying, not for development.

If someone wants to understand why something was done, they must use the repo, and not a source tarball. If they insist on just working with the source snapshot, but ask questions that are answerable in the git history, I cannot support them.

> I write detailed git commit messages like a maniac

I do not think that helps much, in the general case

> The problem with comments is that they also pertain to a revision that existed around the time they were written, but they stick around,

Comments do require maintenance. It is part of professional practice

I think this is fine if you have buy in within your team. Your concerns around temporarily are valid, though using git over comments is a trade off does make understanding a particular bit of code an exercise in reading backwards until you’ve captured the entire context. It also implies some level of fairly consistent discipline from participating members in terms of structuring commits.

That said, git commit messages as a meaningful source of information aren’t for me, I prefer reading the code as a single pane of information. We alleviate concerns about doc strings and comments becoming out of sync with the code by just reviewing comment salience as part of standard code review.

Either way, I think there’s no wrong answers, if it works for you and your team then that’s good.

It's a lot easier, in a code review, to ask for a detailed commit message that conforms to a certain format, than to say things like, "can you add comments?" Which line or change deserves a comment is subjective.

In my open source projects, I use GNU ChangeLog format in the log messages. This mentions every file that is touched, and every defined entity (function, type, macro, variable, ...). In a code review, while it would still be difficult to enforce the quality of what is written about these things in the comment due to subjective reasons, there are objective aspects to it. When reviewing, you can point out something like "you changed the initializer of global variable g_foo, but it's not mentioned in the commit message".

Sure, API comment headers can be enforced reviews. But those are not the comments this discussion is about (and elsewhere I identified these as necessary comments that can't be farmed out into the git log messages).

I like two of the three, but what is the advantage of commenting what the code is doing, when you can use a Trace or Debug message for that instead?

Not the person you are replying to, but I would say that:

- The code 'tells you' what it does

- The comment for the code tells you what the author intended it to do.

The gap between the two is where bugs can be found.

"The comment for the code tells you what the author intended it to do."

Not quite.

The comment for the code tells you what the author of the comment understood the code to do when hen wrote the comment.

It could be that too, but I think that presumes an order - that the comment was written after the code. If the comment was written before the code, then it would describe what the author was trying (intended) to do. Which also implies an order of course.

Yeah, absolutely check who wrote a comment before relying on it

It's luckily rare for people to add wrong comments, though (and those who do should be publicly fustigated).

By the way, please never state something as it were the truth if you're not sure that it is. Saying "I think" is perfectly fine, and might save people days of investigation.

Not the comments I write.

I don't write what the code does or even what "I understand the code to do". I explain choices, especially ones that the next developer or my future self is likely to misunderstand when looking at the code.

But what about a year later when someone's changed the code but not the comment?

I would say that I have observed something like this about as many times as someone has changed some semantics in a way that a variable or function name is no longer correct. That is to say: probably a few times in 25 years, but nothing compared to how much value I have received from them.

>when hen wrote the comment.

I've always said coding is a cottage industry!

https://en.wikipedia.org/wiki/Hen_(pronoun)

I've got no trouble with that perspective, but wouldn't a log message scratch the same itch, plus more?

I've never worked in a company where the commit log message wasn't just a link/reference to something in a bug tracker. I feel like a 'what this block of code does' comment is different from 'what is this change, and why did I make it' commit message.

They meant logging-logs in the code itself:

log.Debugf("Foo is: %#v", ...) //You think: this is probably filtering code log.Debugf("Foo without X is: %#v", ...)

A function generally tells you what it does three times: once in the doc comment, once in the function name, and once in the body.

Putting too much emphasis on na,Ed leads to looooong names

I've seen 64 character variable names

Names should be mnemonic. Reminding, not describing

This is what I tell people: if you're writing a one line code comment, write a debug log message instead.

There's vanishingly few cases where this extra logging statements will ever be a problem and they can all be handled autonomously if they ever are - but it will save everyone else a ton of time in deployment.

You must have extremely busy logs, then? Do you also do this with all the code that runs in loops?

Do you routinely run production services at debug or trace log level?

The point is there's a big difference between "we've got a problem, we need to add logging and redeploy to try and isolate it" versus "we might have a problem, bump the logging level up on that service to see what's going on" (which with the right system you can do without even restarting).

No, I don't. But even when I turn debug/trace on, I want the logs to have a reasonable signal to noise level.

I'm not who you're asking, but I do the same

Re: busy, no because I only enable debug logging when I need it

Re: loops, I wrote a deduplicating logger, so if there are 200 identical messages from within a loop I see:

    {event: "thing happened"}

    {event: "thing happened",
     duplicates: 100, 
     since: "2024-09-11T01:05:00Z",
     reason: "count reached"}

That is, supposing that it's set to saturate at 100 events and they all happen fast enough that it doesn't reset the count. In this case it'll log another batch of 100 on the 201st event.

I think it's important to log the first one immediately, just in case you want to alert on that message. It wouldn't do to wait for the other 99 before raising the alarm.

I wrap my loggers in deduplicators only when I'm about to hand them off to a loop. Otherwise it's the normal ones.

This 'empirical research' is highly doubtful. The first question to ask is what the code with summary comments looked like. While summary comments can sometimes be helpful, this is mostly the case in functions that are relatively long. A question that always arises in that case is whether it is a good idea to split them instead of commenting.

We could have the best of both worlds if comments could be easily hidden, or better yet, just additional meta-data on rich text code. But nope, we can't get away from ascii.

Trouble with comments is that they drift from the code over time because most people do not update the comments - - based upon my surveying production code bases. If they are hidden, it will drift even quicker and become even more useless faster

i think in sean's proposed world we'd have metadata about that too! the comment in the context it was written in would be available, as well as all of the surrounding changes that potentially invalidate it. as well as potentially a whole discussion thread about what they meant when they wrote it, and suggestions about how to change it.

...and the main reason people don't like comments is because they clutter up the code that gives them the truth of the matter. But yes, if they aren't in your face forcing you to look at them rather than the code, then they are slightly more likely to not be ignored when the code is changed.

It would be nice if they could be like footnotes, or boxed out-takes, that could be pushed to side notes. We have had the typography, even if it was just markdown with a rendered code reading mode.

This is caused by poor or nonexistent code review practices. Reviewers should be ensuring that related comments are updated if code functionality is changed.

I would urge developers to err on the side of too many comments over having too few comments, even if there's a risk of them going stale. I can deal with drifting comments, but I can't deal with missing comments.

I've found the opposite. Misleading comments can be far worse than no comments.

Date and sign comments. /* Helps determine staleness -- conrach 2024-09-12 */

You just need a "hide/show comments" extension for your IDE. (I would argue that such a feature should already be built in.)

You don't need to abandon plain text to hide comments. Comments are detectable with a regex; an extension to hide comments would be trivial to make in most editors. I think it's not a common feature because people generally just don't want it.

Rich text code would create so many problems, too. You get locked into a special editor. You need special version control. Grepping becomes difficult. Diffs become difficult. You'd need a whole separate ecosystem, and for what? We have treesitter; we can already treat code like data.

Reply on news.ycombinator.com