DEV Community

Discussion on: Not Documented, Not Done

endontoddy profile image
Andrew Todd • Edited on

Documentation is always a challenge. Not only does a team have to overcome the common aversion to writing it (and I hold my hands up as someone who finds writing docs not as fun as writing code), but there is also the struggle to ensure it stays relevant and up-to-date.

In the same way that data redundancy in a software architecture will constantly cause it's maintainers synchronisation headaches, as will syncing documentation of how code works with the code itself.

I have found that most docs relating to how code works in any sort of detail are doomed to quickly go out of date/sync unless they are inline with the code itself. Even with the best will in the world, people inevitably forget that particular docs exist to be updated.

Even if such docs are available and happen to be up to date, if I'm newly coming in to a project, past experience has taught me not to trust such documwntation too much (for the above reasons), and if you really want to be sure how some business logic actually works, you need to read the code.

So am I saying don't bother? No not at all. But I have found the best approach is to write code to be as self documenting as possible. Good naming and layout of code can help alot here. Where more explicit descriptions are needed code comments can be used.

Well written test suites are also a great way to not only ensure code does the right thing, but to describe what that is.

Where documentation outside of the code can be useful is in describing the high level concepts such as the system design and architecture. These have a fighting chance as they change less often and it tends to be a bigger event when they do. For Http APIs, libs that generate specs for tools like Swagger from the code are also very helpful.