I saw this question:
I made a simple networked game in Java for a university assignment, and I need to document it. I was wondering how real-life developers do this. What is the common and best structure for documentation?
My answer:
Real-life developers do very little old-school commenting and documenting. Instead, clean coding, good naming, and full function signatures so that code is as self-documenting as possible.
With that caveat, best practices are:
- Doc tests: they’re living documentation.
- Type hints or annotations (depending on the language) in function signatures. Again, they’re living documentation.
- Comments for why, not what. Variable names, function names, and type hints/annotations should document the “what”.
- Docs for how to install, what’s in it for the target audience (the WIIFM in marketing-speak), screen shots of the deliverable.
- In algorithmic code, notes on motivation for choosing a particular algorithm, why it’s implemented a particular way, etc.
Dogweather 