Documenting Your Code Base

Plain and simple, good documentation costs money. Either you have to find someone to write documentation full-time or have your developers spend their time (and your money) writing it.  I have never been a part of a situation where writing a tome that exists outside of the code base works. Most developers would not have the time or patience to read it let alone write it. But in a situation where the proper programming language along with its best practices are used, the code’s methods should be self-explanatory.  Then code documentation would only have to be done to explain special cases or addenda.

If your project is especially complex, comprehensive test suites can be used to explain its behaviors and outline its goals. These suites can be executed by a dedicated software tester or by the developer. One way to prevent bad code from clogging the development cycle is to have the developer run a specific set of tests that finds bugs in the code and also performs a functionality smoke test. Then have a dedicated tester run specific tests that ensure the code does what it is intended to do.

The bottom line is you want your people doing what they do best. Developers write code, not documentation. So if your find yourself spending extensive time training new developers on the intricacies of your code, make sure your are following the best practices of the programming language being used, document special cases or addenda, and use comprehensive test suites to cover the rest.