Code Documentation

Code documentation is the application documentation written directly in the source code of the application. Code documentation is used to document the application API in order to increase developer code understanding and discoverability, to reduce the time needed to implement a particular feature using prebuild components and to decrease the defect rate of defects caused by the lack of proper component understanding.

Code documentation is written before each package, class, property and method name in the source code using a specific syntax which makes use of automatic code documentation tools possible. The syntax for code documentation varies from language to language. It is well supported in most IDEs for most of the mainstream development languages.

There are two distinct benefits when using code documentation with automatic tooling support.

First for IDEs that support code completion (intellisense in Visual Studio) the IDE will automatically parse the code documentation of the piece of the code the developer is currently writing and it will present it to the developer as she is typing the code , this informing him of the intended use of the component being used.

Second tools exist that can create a proper API documentation from the source code of an application using code documentation and the basic language syntax as tools. The documentation thus generated is much easier to grok than fumbling in the IDE with code completion and random file opening and reading. Once again tools exists for that , e.g. Sandcastle,Phpdocumentator, Pydoc,Javadoc and etc. the list goes on and on.

A problem most developers I've encuntered have is that they do not know what to write in the code documentation, even when they have written the component them selves.

When I write my code documentation I use the following model for each component memeber I document (class, property, method, package etc...).

Each documetation item is composed of two elements: THE WHAT and THE HOW. Of the two THE HOW is optional since in some cases it is not needed.

This is best shown by an example



/// <summary>
/// THE WHAT : MovieService is a service provider for using basic CRUD operation on the Movie object permanent repository storage(e.g. database )
/// </summary>
///
/// <example>
/// An instance of the MovieService object is created with its static Create method which will connect the object instance to the proper system Movie repository.
///
/// MovieService movieService=MovieService.Create();
/// IEnumerable<Movie> movies= movieService.Select();
/// </example>
public class MovieService
{
/// <summary>
/// THE WHAT: Creates a basic instance of the MovieService object. It does not however intialize the required repository connection for the Movie object.
/// </summary>
private MovieService {}

///<summary> THE WHAT: Creates a basic instance of the MovieService object and intializes the required repository connections for the Movie object.</summary>
/// <returns> Working MovieService intance</returns>
public static MovieService Create{return new MovieService();}

/// <summary> THE WHAT: Returns a collection of all Movie objects in the Movie object repostitors.</summary>
/// <returns>IEnumerable<Movie> collection </returns>
public IEnumerable<Movie> Select() {return new List<Movie>();}
}



The THE WHAT ant the THE HOW texts int he previous example are just for the example sake, in real life documentation endeavors they are not needed, and should not be used.

Document first , document later

There is a great debate in my head, what is best – to document first , or to document latter. The wanna be engineer in my head would scream “Document first!”, but my practical side, the one that has been into the trenches, that has seen things, horrible things would say “Document later!”. How to reconcile those two opposing views?

Documents can be generally be placed into two broad categories, those that are:

• Generally written before development


• Generally written afterwards development

Why do I say Generally? Because in software development nothing is set in stone, and everything is fluid, thus documents cannot be said to have been written always before head or afterwards a piece of software is developed( class, module, library etc.) . A set of documents could be generally written before head, like requirements or the high level architecture, and some are generally written afterwards like in some cases detailed API technical specification.

What makes a document fall into one of the two general categories. Two things :

• Type of document


• Current state of the software life cycle

The Type of the document generally dictates when a software piece will be written. Like, requirements or the functional specification or something like that which is generally needed before a piece of software is written. And some which cannot be (or can, but albeit very hardly depending on the skill of the developer and the knowledge of the system), like detailed technical specification which is not ever accurate when written first and is ever (hopefully) updated once a particular piece of software is written.

The other most contributing factor is the current state of the software life cycle a team find its self in. When developing a green field software it is generally best to do the documentation first ( I'm not discussing waterfall here, you could develop module after module, and before each module write the technical documentation for it before going into development), but when a team finds it self knee deep in a brownfield development project, which generally doesn't have any documentation what so ever, which isn't even commented properly so you cannot generate an API spec automatically which is remotely useful to anyone, when you need to fix unknown defects, when you need to implement a piece of functionality and don't know how to place it inside the project and how it is to be connected to everything else, writing documentation first could be and exercise in futility since you don't know enough about the system. This will change gradually during brownfield development when you will reach a state where writing design documentation first would be a better choice in terms of quality of work and writing speed place into the construction of the document.

So, what to say to may two different parts? It depends. And that is the only answer I can give them, which places my little self once again on the verge of a nervous breakdown due to over thinking so simple things. But documentation is important, some cannot see that, but those cocky bastards will soon find them selves trying to remember how they did that, or where somebody placed this and how is generally this implemented and so on, and will loose valuable money debugging the thing out of its life in order to find something which would take five flimsy minutes to read. Who is stupid now, ha?!