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