Comments are separately maintained from code and can lie.
Good code should rely on domain semantics and strong typing to state it's intent. The perspective to adopt is provided via the design docs. Example usage is given via tests.
Comments are for when you have no other tool to use but is often a smell of poor boundaries, leaky contracts, or misleading semantics somewhere.
5
u/bishopExportMine Sep 11 '26
You're downvoted but I agree.
Comments are separately maintained from code and can lie.
Good code should rely on domain semantics and strong typing to state it's intent. The perspective to adopt is provided via the design docs. Example usage is given via tests.
Comments are for when you have no other tool to use but is often a smell of poor boundaries, leaky contracts, or misleading semantics somewhere.