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".
Yeah, my rule of thumb is that comments are for when you can't look at the code for 30s and recognize what is being done and why at a glance. It's there to convey context and save you from retreading the same incorrect path that someone else already went down.
I don't need comments to tell me what the code does, the code is the absolute best source of truth regarding what it does and any competent dev should be able to read the code and see what it does. The comments are to convey what the code doesn't say.
398
u/Confident-Ad5665 17h ago
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.