Code as documentation, but not the only documentation

image for 'Code as documentation, but not the only documentation' | CAT.Models.Category

Code is the primary (but not the only) form of documentation. But like any documentation it can be clear or gibberish, programmers need to value clarity and learn how to achieve it.

Martin Folwer reiterates the misconception in Agile that "code as documentation" stands that the code is the only documentation rather than having proper supporting materials.

When developing, keep ideas such as below in mind:

  1. Clear and concise naming conventions for methods, signatures, and variables.
  2. Using conventions, wherever possible, rather than hard-coding (routing and database ORMs, for example).
  3. If you feel the NEED for explicit code comments, consider what you could do to simplify the code.
  4. Refactor. Refactor. Refactor. 


This principle comes with a important consequence - that it's important that programmers put in the effort to make sure that this code is clear and readable. Saying that code is documentation isn't saying that a particular code base is good documentation. Like any documentation, code can be clear or it can be gibberish. Code is no more inherently clear than any other form of documentation. (And other forms of documentation can be hopelessly unclear too - I've seen plenty of gibberish UML diagrams, to flog a popular horse.)

Certainly it seems that most code bases aren't very good documentation. But just as it's a fallacy to conclude that declaring code to be documentation excludes other forms, it's a fallacy to say that because code is often poor documentation means that it's necessarily poor. It is possible to write clear code, indeed I'm convinced that most code bases can be made much more clear.

I think part of the reason that code is often so hard to read is because people aren't taking it seriously as documentation. If there's no will to make code clear, then there's little chance it will spring into clarity all by itself. So the first step to clear code is to accept that code is documentation, and then put the effort in to make it be clear. I think this comes down to what was taught to most programmers when they began to program. My teachers didn't put much emphasis on making code clear, they didn't seem to value it and certainly didn't talk about how to do it. We as a whole industry need to put much more emphasis on valuing the clarity of code.

  • code
  • documentation
  • refactoring
author photo - David Longnecker by David Longnecker


Stay Connected