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.

Arhitecture of a thick web application

A thick web application is a application composed of two parts , one is the server which generates HTML , CSS , Javascript and other elements and sends them over a network using the HTTP protocol towards clients who render the received content on the user machine in the form of an interactive user interface, where all the programming elements are tightly bounded in a single application element residing on the server.
Nowadays thick web applications are not the hip thing to do. Everybody is doing service oriented applications or rich internet applications or even cloud oriented applications. Distributed systems are the in of the moment. Thick applications are seen as antiquated, not performing solutions, unable to cope with the requirements expected from modern systems both in the performance/scalability and the maintainability/coolness sides of things.
Everyone forgets that a few years ago every application was a thick application, and that everybody started their careers learning and writing those types of applications. Of course there are still viable cases for such applications to be developed.
First, they are simpler to understand, develop, deploy and maintain. Secondly they can be developed much cheaper and faster than their distributed counterparts due to the lesser numbers of different parts which need to interact and be set up in order to deploy and maintain the thick system in respect to the distributed one.
I’ve actively developed user experience enhanced (web 2.0) applications both in PHP and ASP.NET (with a side note in Django and Google App Engine for a short time) and I’ve found that the following general application architectures is very suitable for developing thick web applications.
The architecture is composed of the following elements (from the front to the back):
Client side modules (screen). This is the top most tier of the application. Here is what is actually sent and executed to the client. Due to the fact how the majority of web application frameworks are organized here we talk about client side code which drives the behavior of a specific module(screen). In lesser respect we talk also about images, video, flash, HTML, and CSS code.
Client side components. This tier is composed of general client side components (once again we talk here mostly about javascript elements – objects and functions) used once or more in one or more client side modules. A client side component is used only for data carrying and data transformation purposes. The required input is provided by the client side code on the each module, and resolution of the task assigned to the client side component is decided by the client side module using the component. Each component must be simple as possible and must do one thing, and one thing only.
Server side modules (screen). This the first server side tier. This tier has two important tasks: first it must generate client side elements sent to the client in response to their request, and the other it must make use of the services provided by the service tier and the API provided by the Domain tier objects returned by the called services in order to compose them in a viable user task. A user task is a set of operations (a workflow) u user must do on the module (screen) in order to achieve a quantifiable business objective.
This tier is where is decided what service (or services and their interactions) must be used in response to a users operation and what message must be sent back to the user in response. This tier must “know” everything that it needs to know about the business problems it tries to solve to successfully communicate with the user.
Server side components. Server side components are composed of reusable elements (classes, functions, widgets or other similar elements) used one or more times in one or more modules. Each component must be used for data carrying or data transformation, it must rely for its required input on the server side module using it and must not decide what to do with its output , which is left to do for the module making use of the component.
Services. This the first tier on the middle tier side. How it is separated from the other middle tiers is not important. What is important how it is used and how it is structured. Regardless of the programming implementation (functional or object oriented) the Service tier must provide a set of stateless, not dependent services each providing an atomic operation. Services must be grouped together by the business task their can perform when used together, but must not make assumptions about the order they are called or the way messages are sent back and forward between the user and the application.
Services must concern themselves with their required input and expected output. If an error condition occurs (invalid parameter etc) the service must raise and exception (or similar message carrying ) construct which will provide technical data to the front end about the error condition occurred. It must not, however, return a full fledged user message.
Domain This tier is tasked with the modeling of the business domain the application is working on. The domain tier is composed from entities, value objects, events and repositories each interacting with each other in the same manner they interact in the business system used by the application. In order to find out more about the Domain tier please read the excellent book written by Eric Evans Domain Driven Design .
This tier is used by both the server side modules and the services. The services will work with input and output parameters taken from the domain tier, and the server side modules will use them to carry out their associated business tasks.
Infrastructure. This tier is used only by the service tier since it provides low level support for interacting with the underlying system, database, other application services and etc. If you need to open and read a file, or send an e-mail message use this tier. What to do with the read data from the file, or what to put in the e-mail message is the job of the server side and services tiers.
Database. The database, or the backend, is the final tier of our typical thick web application architecture. The database is used for permanent data storage, data storage manipulation, querying and fast retrieval. Only one thing is important regarding the implementation of the database: under no condition put a line of application logic in it, no matter how fast or simple it seems to be. It almost always is a bad decision, which will lead to lower system operation visibility and a nightmare of maintenance problems. Just don’t do it. Really.
How to tie all of this together. It’s both simple and terribly complex. What I’ve found out works best is to first design the domain of the application, then translate it into a data model and data transformation procedures. Secondly to define all the business task which must be carried by a user, group them in related modules and break each task into atomic operations which will be actually written as services using the domain tier of input/output.
When writing services I use the following technique: first I ask my self what questions as the user interface I have in order to successfully complete the business task, and then what operations I must perform in order to do it. As the last thing I define the input and output messages for each task/operation.
The infrastructure tier must be made low level as possible. Really low level stuff. The question I ask my self is what I need from the system (world) around me as the services and what I want to be present but also to forget it ever exists. The answer to both question goes into the infrastructure tier.

Short, short deadline sprint rules for success

Imagine this situation, its 24 hours before a very important deadline and your project isn't ready. But you must show some progress to the client, something anything to stop them from stopping the project and turning to someone else. What do you?

I've been caught in this situation several times already this year, and will in all probability caught again, and its not easy or simple to handle. For each project I was a technical lead, and the responsibility to actually do the task by the deadline fell to me.

The following rules helped me:

1. Cash in your relationship chips , you'll need them to motivate your people and make them buy in the effort required of them.


2. Write a task list of all tasks needed to be carried out in order to successfully meet the dead line, and then filter it out to the bare essential. It's time for brutal reality, not Christmas wish list making.


3. Take the core, the most difficult and most important stuff on your self. They made you a technical lead for a reason. Now is time to earn it.


4. Distribute the remaining stuff to each team member according to their capabilities and aptitude.


5. Make sure no one introduces new (or reopens) new defects into the system. Test the core twice before committing. Break heads if necessary. It's not the time to create more work.


6. Do not commit unfinished work. It either is done, or it isn't. Only pure 100% completed and tested changes go into the repository. Make sure everyone is on the level with this.


7. Do standups every four hours in the first twelve hour period, then switch to two hour standups for the remainder of the sprint. Track only completed, not completed progress on the created task list. Look for problems, and replace people who got tired or the tasks assigned to them are to difficult to handle. Pair programming was proven effective in both cases.


8. On achieving all (or the majority) of the planned task code freeze the repository, and label it as such. Do not allow anyone to commit now unless its a critical defect fix you personally authorized. Break heads if necessary.


9. After the code was freezed, test everything on your machine. If everything checks out label the code in the repository as such.


10. Publish the product to the production environment and then check it there once again. If everything checks alright, go home to your family for a head bashing for spending 24 hours on work while your kid won he's first soccer prize (or similar). Be proud of your self for achieving something great and meaningless.

The following rules(principles, steps) work because there is a clear scope of the work to do in a very short amount of time. Everyone is clear on the importance of the work to do and what is the price of failure.

The two most important thins are frequent standups and the written, prioritized task list. Why? Frequent standups remind everyone one the goals and the principles of the work to do. They allow faster knowledge sharing between team members and allow you to get a clear view of the progress achieved thus far, of the problems had and allow you to frequently react to those problems in order to remove the impediments thrown in front of the team.

Remember in the end everything falls to you. You must be the leader, the one that starts first and goes home the last. The one that pushes the code to the production and says is done. At four am there is no one else. Its your responsibility to sleep for two hours and show to work to check if everything is OK with the business people showing the product to the client.

You are the hart and soul of the team. You must show firmness and clarity of vision and command, you must be supportive because without them you are nothing . You are your team, and they are yours for good and for worse.