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.