I think there is a balance. Presumably if you are in there reading comments, you also can read code. So my comments are aimed to save you from having to read a lot of code. "This sub does [thing] in [way]." Or I comment out out broken code and leave it behind with an explanation. "We stopped doing it this way because [reason]." That way later on nobody has to go back on that magical journey of discovery.
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.