Meanwhile, some colleagues: "Code should have as little comments as possible, the code should explain itself." (conceptually not wholly wrong, but it can only explain HOW not WHY and even then often insufficiently) all while having barebones/empty README.md files more often than not. Fun times.

▲

zingar 6 hours ago | parent | next [-]

Actually good naming does plenty to explain the why. And because it’s part of the code it might actually be updated when it stops being true.

▲

jcgrillo 6 hours ago | parent | prev | next [-]

Comments are great until they diverge from the code. The "no comments, just self-explanatory code" reaction comes from the trauma of having to read hundreds of lines of comments only to discover they have nothing to do with how the code actually works, because over time the code has received updates but the comments haven't. In that case it's better to just have no comments or documentation of any kind--less cognitive overhead. This is a symptom of broken culture, but the breakage is the same kind that has managers salivating over LLM vibeslop. So I totally get where your colleagues might be coming from. Working within the confines of how things actually are it could be totally reasonable.

▲

sfn42 4 hours ago | parent [-]

This is honestly such a bad argument against comments.

I'm gonna note down my reasons for doing things and other information I deem useful, and if some other dipshit 5 years from now when I've moved on comes along and starts changing everything up without keeping the comments up to date that's their problem not mine. There was never anything wrong with my comments, the only thing that's wrong is the dipshit messing things up.

Doesn't matter what I do, the dipshit is going to mess everything up anyway. Those outdated comments will be the least of their worries.

▲

krupan 27 minutes ago | parent | next [-]

And then you find out the dipshit that didn't keep the comments up to date was you all along

	▲	sfn42 26 minutes ago \| parent [-]
		It wasn't.

▲

jcgrillo 3 hours ago | parent | prev [-]

> that's their problem not mine

IME unfortunately that's not actually the case. It very much is your problem, as the architect of the original system, unless you can get yourself transferred to a department far, far away. I've never managed that except by leaving the company.

To be clear, I don't believe it should be this way, but sadly unless you work in an uncommonly well run company it usually is.

	▲	sfn42 32 minutes ago \| parent [-]
		I really can't imagine this ever becoming a real problem. Not once have I ever worked in a place where any kind of leadership would ever give a shit about comments nor anything else in the code itself. The lowest level leadership has ever gone is click a button to see if it works. And if anyone has a problem with comments existing it's trivial to find/replace them out of existence. Literally a one minute job, if you actually think the codebase would be better without them. This is such a humongous non-issue it's crazy man.

▲

Pxtl 7 hours ago | parent | prev [-]

> the code should explain itself.

This is a good goal. You should strive to make the code explain itself. To write code that does not need comments.

You will fail to reach that goal most of the time.

And when you fail to reach that goal, write the dang comments explaining why the code is the way that it is.

▲

bandrami 4 hours ago | parent [-]

But you will also fail to keep the comments and code synchronized, and the comment will at some point no longer describe why the code is doing whatever it does

	▲	jaxn 3 hours ago \| parent [-]
		But copilot code review agent is pretty good at catching when code and comments diverge (even in unrelated documentation files).