Docs Rot. Tests Don’t.

Software documentation falls into two buckets: high-level architectural documentation and low-level descriptions.

High-level documentation is wonderful. It gives your team an appropriate lay-of-the-land they need to understand the project as a whole.

Low-level documentation is a waste of time and should be avoided unless special circumstances make it necessary — for example, documenting the return value of query.destroy_all in a Rails controller, where a subtle behaviour could trip up other developers.

Low-Level Documentation Is Dead by Default

The biggest problem with code documentation is that it is dead by default. If you document your code well, then change the code, that documentation is no longer correct. You need to update it and verify that the new documentation is accurate.

If you do nothing, your documentation won’t assist you — because it’s dead.

With TDD, your tests are executable. If you change your code, tests will start failing. This means you have a checklist of changes needed to bring the system back to a stable state. Once all the tests pass again, you know your system has been successfully updated.

If another developer needs to understand how a piece of code works, your tests will show real, working examples — not just explain it. And because tests are living, executable code, you know those examples are current and reliable.

Don’t rely on documentation that silently rots. Use tests — they grow with your code, stay honest, and always run.