By Martin Jul
We’re six months into a project. The code base is 53,000 statements, 2/3 of which are tests.
We have been working 6 months according to a set of standards: test-driven development with unit and integration tests, model-view-control architecture, NHibernate OR-mapping for the persistence layer, and the Castle container for weaving it all together.
Then an external consultant shows up. He has been hired to check the quality of the work to ensure that a “normal” developer can take the code and work with it inside a “reasonable” amount of time.
I convince him to look at a few architecture diagrams, before he starts looking at the code. I try to show him how to find the implementation code corresponding to the tests but he is not interested in the tests. His goal is to ensure that code is properly documented – and in his world this means the implementation only, not the tests.
Instead he starts at the top with one of the client applications, a web-based intranet for editing data in the system. He starts browsing the code – looking through the container and some of the controller and model classes that it uses.
A few weeks later we get a report.
There should be more comments in the code (our guideline is to write simple, readable code rather than spaghetti with comments).
Oh and member variables should be prefixed with an m, value parameters with a v and reference parameters with an r. And the type of a variable must be derivable from its name.
He also raises a number of concerns about the use of NHibernate and Castle. Basically he wants us to write documentation for these as well (never mind they come with documented source and books and on-line articles).
More or less the audit says to use his idea of what constitutes a good project. So basically he is testing the documentation quality against an arbitrary set of requirements.
We need to devote a lot of effort to convince him.
So, note to self – a pragmatic solution for documentation and auditing:
- Write a simple developers handbook with coding and documentation guidelines etc. and have the customer sign it off.
- Involve the auditor early to check the guidelines.
- Use the handbook as the guideline for audits.
- In any event have the auditor provide a set of “functional requirements” to the documentation, e.g.. “it should be possible to easily find out what a method is doing” rather than saying arcane things like “there should be a two lines of comments for every branch statement”.
- Create a HOWTO document for each of these requirements and add it to the developer handbook: for example, “The requirements are captured in integration tests using the Selenium tool, they are named so and so.” etc..
