undefined

points

[-]

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.

by zingar1 hours ago|

parent|

[-]

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.

by jcgrillo2 hours ago|

parent|

prev|

[-]

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.

by sfn4223 minutes 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.

by Pxtl3 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.

by hk__23 hours ago|

prev|

[-]

This is also a great way to ensure the documentation is up to date. It’s easier to fix the comment while you’re in the code just below it than to remember “ah yes I have to update docs/something.md because I modified src/foo/bar.ts”.

by CharlieDigital3 hours ago|

parent|

[-]

People moving docs out of code are absolutely foolish because no one is going to remember to update it consistently but the agent always updates comments in the line of sight consistently.

Agent is not going to know to look for a file to update unless instructed. Now your file is out of sync. Code comments keeping everything line of sight makes it easy and foolproof.