Geeks With Blogs
CodeSeeker Just another developer trying to do the right thing

In the last couple of shops I've worked that actually have documentation, what I have tried to accomplish with the developer documentation for the code was to be able to reproduce the code from the documentation. The documentation should give an overview of the page, contain all of the requirements and business rules in the Analyst documentation, and address all of the events that can occur on the page. How are fields populated? What gets validated when a button is clicked? If the application has multiple layers, all layers should be documented including the database stored procedures, user-defined functions, etc.

It's good to be able to do this type of documentation prior to release to the QA folks. Reason being, by giving the code this close of a second look, you often find stuff that was forgotten, is incorrect, or could clearly be done a lot better. Then it becomes part of the development process itself, not just an afterthought.

This of course is in addition to method header comments, self-documenting code (for example, naming variables and methods in such a way as to make the code tell you what it does just by reading the code itself), other comments in the code for more complex code or assumptions, avoiding the use of "magic numbers" (numbers in the code that have meaning but are not explained), and other coding best practices.

Posted on Monday, August 25, 2008 2:50 PM | Back to top

Copyright © Mike Ellis | Powered by: