News for hackers. Stuff that matters.
Re:Why Not Comments by abc-1 on Tuesday September 10, 2024 @06:26PM (#41506237)
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.
Re:Why Not Comments by Prickle on Tuesday September 10, 2024 @06:29PM (#41506262)
I was taught to not leave comments in finished code.

I have regretted following that lesson ever since.

Re:Why Not Comments by acbart on Tuesday September 10, 2024 @06:34PM (#41506286)
If code were ever finished, then perhaps this would make sense :)
Re:Why Not Comments by spacechild1 on Tuesday September 10, 2024 @06:35PM (#41506301)
Who taught you that!?
Re:Why Not Comments by Prickle on Wednesday September 11, 2024 @12:01AM (#41507907)
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.

Re:Why Not Comments by thayne on Wednesday September 11, 2024 @12:18AM (#41507974)
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.

Re:Why Not Comments by RandallBrown on Wednesday September 11, 2024 @12:56AM (#41508135)
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.

Re:Why Not Comments by moring on Wednesday September 11, 2024 @03:30AM (#41508943)
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.

Re:Why Not Comments by atoav on Wednesday September 11, 2024 @03:59AM (#41509124)
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.

Re:Why Not Comments by exe34 on Wednesday September 11, 2024 @06:19AM (#41509912)
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.
Re:Why Not Comments by netdevnet on Wednesday September 11, 2024 @06:39AM (#41510037)
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
Re:Why Not Comments by bccdee on Wednesday September 11, 2024 @11:12AM (#41512120)
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.
Re:Why Not Comments by atoav on Wednesday September 11, 2024 @03:41AM (#41509011)
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.

Re:Why Not Comments by netdevnet on Wednesday September 11, 2024 @06:41AM (#41510052)
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

Re:Why Not Comments by dspillett on Wednesday September 11, 2024 @07:05AM (#41510177)
> 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”).

Re:Why Not Comments by f1shy on Wednesday September 11, 2024 @08:01AM (#41510508)
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.

Re:Why Not Comments by dodos on Wednesday September 11, 2024 @03:31AM (#41508950)
I had a professor in college who would grade you down if there were any comments in your code.
Re:Why Not Comments by forgotpwd16 on Wednesday September 11, 2024 @05:28AM (#41509652)
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.
Re:Why Not Comments by dspillett on Wednesday September 11, 2024 @07:10AM (#41510195)
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”!

Re:Why Not Comments by readthenotes1 on Tuesday September 10, 2024 @06:57PM (#41506466)
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.

Re:Why Not Comments by gus_massa on Tuesday September 10, 2024 @08:15PM (#41506985)

  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.
Re:Why Not Comments by hansvm on Wednesday September 11, 2024 @09:32AM (#41511196)
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.
Re:Why Not Comments by DanHulton on Wednesday September 11, 2024 @12:00PM (#41512621)
One step further:

    DAY_IN_SECONDS = 24 * 60 * 60
Re:Why Not Comments by throwaway14356 on Wednesday September 11, 2024 @11:48PM (#41517409)
SECONDS_PER_MINUTE = 60;

MINUTES_PER_HOUR = 60;

HOURS_PER_DAY = 24;

DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

Re:Why Not Comments by CRConrad on Thursday September 12, 2024 @02:48AM (#41518204)
> 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) ;

Re:Why Not Comments by g-b-r on Tuesday September 10, 2024 @07:58PM (#41506874)
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

Re:Why Not Comments by GianFabien on Tuesday September 10, 2024 @08:26PM (#41507041)
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.
Re:Why Not Comments by dspillett on Wednesday September 11, 2024 @07:11AM (#41510206)
> 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.

Re:Why Not Comments by jjav on Tuesday September 10, 2024 @09:37PM (#41507358)
> 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.

Re:Why Not Comments by dllthomas on Wednesday September 11, 2024 @02:29AM (#41508570)
I once came to a complicated, multi threaded C++ program and saw:

   using namespace std; // using namespace standard
Re:Why Not Comments by f1shy on Wednesday September 11, 2024 @08:06AM (#41510539)
I'm working RIGHT NOW in a codebase where before each function definition there is a comment "// Function"
Re:Why Not Comments by bccdee on Wednesday September 11, 2024 @11:14AM (#41512143)
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.

Re:Why Not Comments by f1shy on Friday September 13, 2024 @11:02AM (#41531882)
With a half decent IDE you do not need it. It is inexcusable.
Re:Why Not Comments by bccdee on Saturday September 14, 2024 @02:09PM (#41541627)
Oh I agree, but the person who put them there must have had some sort of reason, even if it's a bad one.
Re:Why Not Comments by dllthomas on Tuesday September 17, 2024 @01:40PM (#41570405)
> 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.

Re:Why Not Comments by throwaway14356 on Wednesday September 11, 2024 @11:25PM (#41517289)
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.

Re:Why Not Comments by imp0cat on Wednesday September 11, 2024 @01:20AM (#41508230)
Code is never finished, only abandoned.
Re:Why Not Comments by hi_hi on Wednesday September 11, 2024 @05:31AM (#41509676)
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.

Re:Why Not Comments by CRConrad on Thursday September 12, 2024 @02:25AM (#41518123)
> 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.

Re:Why Not Comments by fragmede on Thursday September 12, 2024 @02:41AM (#41518172)
What's stopping you from installing it?
Re:Why Not Comments by CRConrad on Friday September 13, 2024 @08:56AM (#41530808)
I'm not the server admin. I don't even know who is. Ours is not to ask why, ours is but...
Re:Why Not Comments by __MatrixMan__ on Tuesday September 10, 2024 @06:39PM (#41506331)
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?
Re:Why Not Comments by PlunderBunny on Tuesday September 10, 2024 @06:51PM (#41506407)
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.

Re:Why Not Comments by readthenotes1 on Tuesday September 10, 2024 @07:00PM (#41506506)
"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.

Re:Why Not Comments by PlunderBunny on Tuesday September 10, 2024 @07:58PM (#41506871)
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.
Re:Why Not Comments by g-b-r on Tuesday September 10, 2024 @08:14PM (#41506979)
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.

Re:Why Not Comments by kristiandupont on Wednesday September 11, 2024 @01:53AM (#41508393)
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.

Re:Why Not Comments by readthenotes1 on Thursday September 12, 2024 @09:25AM (#41520672)
But what about a year later when someone's changed the code but not the comment?
Re:Why Not Comments by kristiandupont on Thursday September 12, 2024 @12:58PM (#41522963)
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.
Re:Why Not Comments by ykonstant on Wednesday September 11, 2024 @02:52AM (#41508693)
>when hen wrote the comment.

I've always said coding is a cottage industry!

Re:Why Not Comments by CRConrad on Thursday September 12, 2024 @03:10AM (#41518291)
Re:Why Not Comments by __MatrixMan__ on Tuesday September 10, 2024 @09:14PM (#41507275)
I've got no trouble with that perspective, but wouldn't a log message scratch the same itch, plus more?
Re:Why Not Comments by PlunderBunny on Wednesday September 11, 2024 @12:49AM (#41508110)
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.
Re:Why Not Comments by porridgeraisin on Wednesday September 11, 2024 @01:39AM (#41508316)
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", ...)

Re:Why Not Comments by edflsafoiewq on Tuesday September 10, 2024 @06:54PM (#41506434)
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.
Re:Why Not Comments by worik on Wednesday September 11, 2024 @03:46PM (#41514716)
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

Re:Why Not Comments by XorNot on Wednesday September 11, 2024 @04:41AM (#41509373)
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.

Re:Why Not Comments by kristiandupont on Wednesday September 11, 2024 @06:09AM (#41509859)
You must have extremely busy logs, then? Do you also do this with all the code that runs in loops?
Re:Why Not Comments by XorNot on Wednesday September 11, 2024 @06:38AM (#41510036)
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).

Re:Why Not Comments by kristiandupont on Thursday September 12, 2024 @06:08AM (#41519218)
No, I don't. But even when I turn debug/trace on, I want the logs to have a reasonable signal to noise level.
Re:Why Not Comments by __MatrixMan__ on Wednesday September 11, 2024 @03:03PM (#41514334)
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.

Re:Why Not Comments by seanmcdirmid on Tuesday September 10, 2024 @06:56PM (#41506449)
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.
Re:Why Not Comments by readthenotes1 on Tuesday September 10, 2024 @06:59PM (#41506485)
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
Re:Why Not Comments by shiroiushi on Tuesday September 10, 2024 @08:04PM (#41506915)
This is caused by poor or nonexistent code review practices. Reviewers should be ensuring that related comments are updated if code functionality is changed.
Re:Why Not Comments by seanmcdirmid on Tuesday September 10, 2024 @07:39PM (#41506762)
...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.

Re:Why Not Comments by convolvatron on Tuesday September 10, 2024 @07:38PM (#41506756)
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.
Re:Why Not Comments by yen223 on Wednesday September 11, 2024 @03:27AM (#41508923)
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.
Re:Why Not Comments by wtetzner on Wednesday September 11, 2024 @10:34AM (#41511765)
I've found the opposite. Misleading comments can be far worse than no comments.
Re:Why Not Comments by CRConrad on Thursday September 12, 2024 @03:49AM (#41518491)
Date and sign comments. /* Helps determine staleness -- conrach 2024-09-12 */
Re:Why Not Comments by kmoser on Tuesday September 10, 2024 @11:27PM (#41507759)
You just need a "hide/show comments" extension for your IDE. (I would argue that such a feature should already be built in.)
Re:Why Not Comments by bccdee on Wednesday September 11, 2024 @11:22AM (#41512220)
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.

Re:Why Not Comments by hughesjj on Tuesday September 10, 2024 @08:22PM (#41507019)
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

Re:Why Not Comments by AtlasBarfed on Wednesday September 11, 2024 @01:11AM (#41508193)
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"

Re:Why Not Comments by answerheck on Wednesday September 11, 2024 @02:14PM (#41513888)
Copy that. CC has done a lot of harm in some ways.
Re:Why Not Comments by appplication on Wednesday September 11, 2024 @02:09AM (#41508478)
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.
Re:Why Not Comments by answerheck on Wednesday September 11, 2024 @02:17PM (#41513915)
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!
Re:Why Not Comments by kazinator on Wednesday September 11, 2024 @02:26PM (#41513976)
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.

Re:Why Not Comments by appplication on Wednesday September 11, 2024 @03:50PM (#41514765)
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.

Re:Why Not Comments by kazinator on Wednesday September 11, 2024 @10:50PM (#41517116)
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).

Re:Why Not Comments by worik on Wednesday September 11, 2024 @03:40PM (#41514665)
> 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

Re:Why Not Comments by cjfd on Wednesday September 11, 2024 @05:52AM (#41509772)
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.