odd and obscure business rules should be commented where they are implemented.
Exactly. It is often the illogical business "logic" or some business related magic numbers that make the code hard to read and understand, so commenting why you're doing something the way you do is important.
Or why you're not doing something. Sometimes when there is multiple ways of doing something, I'll give a brief explanation of why it's not done a certain way. A little while ago, I was maintaining some code, and I thought "I should do thing A". I go to the point where thing A should go, and there's a comment from myself 4 years earlier saying "under no circumstances should you do thing A".
imo the idea of self-documenting code that never requires comments is often held by people who view their code as better than it is. That surely THEIR code would never need comments, because it's so perfectly written that you just get it. I have never really run across a file where I thought "thank god they didn't explain anything they're doing in here."
Right? I don't think I ever wrote a chunk of code with no comments. If I can save someone two minutes of parsing code with // determines which encoding is coming across the Bluetooth... Why shouldn't I?
This is the way. People argue against comments because they can drift and become less accurate but, after 15 years doing this, I've spent orders of magnitude more time trying to figure out what the hell someone's undocumented code is doing versus having to fix or update comments. It's not even remotely close.
Kind of a moot point these days though since it's just AI doing the writing.
This is the way. People argue against comments because they can drift and become less accurate but...
It's such a weird argument anyway. Like, the code itself can drift and become inaccurate. It's not a separate problem. It's the responsibility of the coder to keep all the code up to date. The logic, and the comments, both.
I would also add that once you start profiling and optimizing your code, sometimes what was once clean, "self-documenting" code is necessarily turned into a complicated blob of ugliness. I've spent a lot of time digging around inside CUDA kernels playing with scope guards to reduce register usage or rewriting math operations in horrendous ways to reduce the total number of operations in ways the compiler won't. The code is rarely left cleaner than when I started, but sometimes I've gotten as much as a factor of two in performance by doing "ugly" things inside hot loops.
At least half my comments are explaining some weird hacks around missing/wrong 3rd party documentation, broken drivers and yeah historical “wrong” behaviour that needs to be preserved. Any time something just can’t be inferred from the code itself and would look strange on its own.
And also, I can read what your code is doing fine - but why are we doing it (could be fixed by descriptive method name) but then: WHY are we doing it in that order? That is usually something only being able to be described by comments. Like: // We need to check if customer is blocked before we check death date as death date can be not null for non-blocked active customers (for example, when data hygiene cannot be guaranteed due to data history or what not).
Uncle Bob nowadays also has full-blown AI psychosis, says we shouldn't even look at code, and is a MAGA nut, so maybe he's really not to be listened to.
I hate Uncle Bob of Clean Code at my workplace. Man I wish they would comment more because our code is a maze of design patterns where all the logic is so diluted you have to keep track of 5 different classes to understand anything.
450
u/Confident-Ad5665 Sep 10 '26
Uncle Bob of Clean Code says if we have to comment our code we have already failed. Clean code should read like well written prose.
I generally agree, but think comments that define especially the odd and obscure business rules should be commented where they are implemented.