Don’t do it, a comment is a lie waiting to happen
- If a comment is needed because the code is unclear, move it into it's own method with a nice name.
- Write a unit test to explain things instead of using code comments.
- Unit tests are executable, self verifying documentation.
It’s the universal ‘check here first’
- introduce the project
- show basic usage
- mention any problems or gotchas
- Readme driven development
Helps high level design discussions
- After a while you just toss them
- CRC cards
- OmniGraffle for visualisng relationships
And blogs kind of following the same thing – there’s the documentation that’s not necessarily – I mean, sometimes it is but not necessarily written by the people who wrote the code, but it’s still valuable in the sense that it helps you gain context and get a handle on what it’s supposed to be doing.