Code Documentation
Definition
Code Documentation is the practice of recording explanatory information about the code — either embedded within the source code (inline comments, docstrings) or as separate documents — to help others (and your future self) understand, use, and maintain the software.
Types of Code Documentation
1. Internal (In-code) Documentation
- Comments — explain non-obvious logic, decisions, or warnings within the code
- Docstrings/Function Headers — describe what a function does, its parameters, return values, exceptions
- Naming — meaningful variable/function names are itself a form of documentation
2. External Documentation
- API Documentation — describes available functions/endpoints, parameters, usage (e.g., generated via tools like JSDoc, Sphinx, Javadoc)
- README files — project overview, setup instructions, usage examples
- Design Documents — architecture diagrams, module descriptions
- User Manuals — how end-users operate the software
What Good Comments Should Explain
- Why, not just what the code does (the code itself shows "what"; comments should explain why a particular approach was taken)
- Non-obvious edge cases or business rules
- Warnings about tricky code, workarounds, or known limitations
Good Documentation Practices
- Keep documentation up to date with code changes (stale docs are worse than no docs)
- Document public interfaces (functions/classes others will use) thoroughly
- Avoid redundant comments that just restate the code (
i++; // increment i) - Use standard documentation generation tools (Javadoc, Sphinx, JSDoc) for consistency
- Include setup/installation instructions in README for new developers
Why Documentation Matters
- Supports maintainability — future developers (including you) understand the "why" behind decisions
- Reduces onboarding time for new team members
- Essential for API/library consumers who don't have access to the internal implementation
- A required deliverable in most formal SDLC processes (part of the SRS/design/final delivery)
Consequence of Poor Documentation
- Increases maintenance cost significantly (developers waste time reverse-engineering intent)
- Higher risk of introducing bugs when modifying undocumented code
- Slower onboarding, knowledge silos (only original author understands the code)
Exam tip: Emphasize the distinction between internal (comments/docstrings) and external (README, API docs, user manuals) documentation, and the principle "comments should explain WHY, not WHAT" — a commonly tested conceptual point.