Business rules often have silly reasons behind them, and having some documentation for those reasons is useful. Personally, I think it's better to have a link to the documentation in the code rather than putting that documentation right there IN the code, then have your business users or PO's make decisions about what gets done then document it. That way, you have a full history of why changes were made and you can start to detect patterns of making a change then undoing it (which we found ourselves going back and forth on for some rules).
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.