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.

For

1. 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.
2. Up-to-Date: Documentation can often become outdated as the code evolves, but the code itself is always up-to-date.
3. 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.
4. No Duplication: Documenting something that is already very clear in code could be considered redundant, leading to the “Don’t Repeat Yourself” (DRY) principle.

Against

1. 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.
2. 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.
3. Comments & Annotations: Even the most well-written code benefits from comments and annotations that explain tricky or non-intuitive sections of code.
4. Not Always Possible: Some languages, frameworks, or problems are so complex that the code can’t be made self-explanatory.
5. 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.
6. 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.

Balance

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.

References

• “CodeAsDocumentation” by Martin Fowler, quoted in the article are:
  • “Refactoring” by Martin Fowler, with Kent Beck
  • “Refactoring to Patterns” by Joshua Kerievsky
• “Code as Design: Three Essays by Jack W. Reeves”, includes:
  • “What Is Software Design?”
  • “What Is Software Design: 13 Years Later”
  • “Letter to the Editor (Precursor to What Is Software Design?)”
• “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.