The phrase “the code is the documentation” captures an idea that is somewhat controversial within the software development community. Personally, while I tacitly agree, I find it elitist and exclusionary, the barrier, being of course, the ability to “read” code to a sufficient level to be able to interpret it meaningfully. But that’s just my subjective opinion, here are some aspects that illuminate different viewpoints in a more objective and balanced manner.
- Self-Explanatory Code: If code is well-written, it should be somewhat self-explanatory. Good code will be organized, follow conventions, and be concise, making it easier to understand what is happening.
- Up-to-Date: Documentation can often become outdated as the code evolves, but the code itself is always up-to-date.
- Conciseness: Sometimes code is actually easier to understand than a long-winded explanation. This is especially true for developers who are already familiar with the language and domain.
- No Duplication: Documenting something that is already very clear in code could be considered redundant, leading to the “Don’t Repeat Yourself” (DRY) principle.
- Lack of Context: Code can tell you the “how,” but not the “why.” Context, rationale, and high-level overviews are often best conveyed through documentation.
- Barrier to Entry: For those who aren’t intimately familiar with the language, tools, or the project itself, jumping straight into code can be daunting. Documentation provides a smoother entry point.
- Comments & Annotations: Even the most well-written code benefits from comments and annotations that explain tricky or non-intuitive sections of code.
- Not Always Possible: Some languages, frameworks, or problems are so complex that the code can’t be made self-explanatory.
- Maintenance: Well-maintained documentation can serve as a guide for future development, helping developers understand not just how to use the code, but how to extend or modify it.
- Non-Technical Stakeholders: Documentation isn’t just for developers; it’s often crucial for managers, testers, and others who have a stake in the project but may not be able to understand the code.
Most experienced developers advocate a balanced approach:
- Code should be as clean and self-explanatory as possible, but supplementary documentation should be provided where necessary.
- “Living Documentation,” which is generated directly from the codebase but includes human-written comments, can offer a compromise.
- AI can generate documentation from even the oldest of code bases, but whether the insights are truly valuable is yet to be seen.
In summary, while well-written code can certainly reduce the need for extensive documentation, it’s generally a stretch to say that the code is the only documentation you need. A well-documented codebase, supplemented by additional guides, architecture diagrams, and the like, usually results in a project that is easier to understand, maintain, and extend.
- “CodeAsDocumentation” by Martin Fowler, quoted in the article are:
- “Code as Design: Three Essays by Jack W. Reeves”, includes:
- “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin: This book discusses how to write clean, maintainable code and implicitly touches on the idea that well-written code serves as its own form of documentation.
- “Code Complete: A Practical Handbook of Software Construction” by Steve McConnell: This book covers a broad range of software construction topics, including the importance of comments and documentation.
- “The Pragmatic Programmer: Your Journey to Mastery” by Andrew Hunt and David Thomas: This book provides general advice on software development, including the benefits and pitfalls of documentation.
- “Design Patterns: Elements of Reusable Object-Oriented Software” by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides: This book introduces design patterns and provides some insight into the documentation necessary to understand and implement them effectively.
- “Documenting Software Architectures: Views and Beyond” by Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Paulo Merson, Robert Nord, and Judith Stafford: This book specifically focuses on the importance of documenting software architectures and provides various methods to do so.