alt Hacker NewsMeanwhile, 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.
Replies
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.
> 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.
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.