Adapting Code Documentation Practices

Today I recieved a decree from above to start spot checking code for proper documentation and if I don't deem the documentation effort to be adequate, I need to tell the QA not to accept the project.


Implementing this decree will be tricky socially, technically, and logistically. On the social front, it will be difficult to gain the necessary buy-in from other developers, who may perceive spot checks as being too Big Brotherly and invasive. Technically, documenting every function is wasteful, we'll need to define exactly what type of functions and classes are in most need of javadocs. And finally logistically, we need to find answers to questions like "How do we enforce these rules?" "How do we plug this new requirement into our existing processes?" "How do we measure our progress and the level of compliance?"


Documentation for documentation's sake is pointless and wasteful. I believe the best approach in satisfying all three areas is to look at the Agile Manifesto and start implementing the process with a single goal in mind: to maximize each and every principle of agile development. Doing so, will help us focus our reasons (we may end up finding that there are none), define criteria for gathering performance metrics, and most importantly will provide the grounds for a successful buy-in from the management and developers.