[purerandomness]

Avoiding comments is an exercise in thinking how to rename or refactor a function, or a variable in such a way that a junior developer will be able to read it like prose, and immediately understand what's going on.

It's cognitively stressing, but is beneficial for juniors, and developers new to the codebase, just as it is for senior developers to reduce the mental overhead for the reader.

It's always good to spend an extra minute thinking how to avoid a comment.

Of course there are exceptions, but the mental exercise trying to avoid having that exception is always worth it.

Comments are instant technical debt.

Especially junior developers will be extremely confused and slowed down by having to read both, the comment, and then the code, which was refactored in the meantime and does the opposite of what the comment said.

[pmarreck]

This is awfully purist.

I think a happy medium of "comment brevity, and try thinking of a clearer way to do something instead of documenting the potentially unnecessary complexity with a comment" would be good.

I don't know where this "comments are instant technical debt" meme came from, because it's frankly fucking stupid, especially in the age of being able to ask the LLM "please find any out-of-date comments in this code and update them" since even the AI-averse would probably not object to it commenting code more correctly than the human did

[ragequittah]

Not commenting code seems like the most unhinged thing I can think of. We don't need blueprints to build this building gestures broadly isn't it obvious to the construction workers where to put everything?

[purerandomness]

The blueprint is the code.

[robertfw]

I don't know, I tend to agree. I feel like the number of times I've been thrown off by an out of date comment for code that could have probably been refactored to be clearer, outweigh the times a comment has helped.

Docstring comments are even worse, because it's so easy for someone to update the function and not the docstring, and it's very easy to miss in PR review

[sfn42]

As always the problem isn't the actual thing being discussed - the problem is shitty developers who wrote shitty comments and/or don't update comments when they update code.

Good and up to date comments are good and up to date. Bad and outdated comments are bad and outdated. If you let your codebase rot then it rots. If you don't then it doesn't. It's not the comment's fault you didnt update it. It's yours.

[purerandomness]

It's always a skill issue.

Guard rails should be there to prevent inexperienced developers (or overworked, tired ones) from committing bad code.

"Try to think how to refactor functions into smaller ones and give them meaningful names so that everyone knows immediately what's going on" is a good enough guard rail.

[purerandomness]

> "comment brevity, and try thinking of a clearer way to do something instead of documenting the potentially unnecessary complexity with a comment"

That's exactly what I wrote, phrased slightly differently.

We both agree at the core.