Maybe Comments _Should_ Explain 'What'
4 months ago
- #programming
- #clean-code
- #code-comments
- Comments should explain both 'what' and 'why', not just 'why'.
- Descriptive variable names reduce the need for 'what' comments but don't eliminate context switches.
- Storing 'why' in commit messages or tests can make it harder to find and understand the reasoning behind code.
- Extracting methods for cleaner code can introduce context switches when debugging or understanding the flow.
- Well-placed 'what' comments can sometimes be more effective than method extraction for understanding code.
- The article argues against the blanket rejection of 'what' comments, suggesting they have valid use cases.