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.

Best practices in brownfield development

The wikipedia definition for the term 'brownfield is this : ''In the United States city planning jargon, brownfield land (or simply a brownfield) is land previously used for industrial purposes or certain commercial uses. The land may be contaminated by low concentrations of hazardous waste or pollution, and has the potential to be reused once it is cleaned up. Land that is more severely contaminated and has high concentrations of hazardous waste or pollution, such as a Superfund site, does not fall under the brownfield classification. Mothballed brownfields are properties which the owners are not willing to transfer or put to productive reuse.[2]' .

I couldn't agreed more with this definition, especially about the hazardous waste and pollution parts. Brownfield development in software industry is very common, rarely a developer will develop a system from scratch without dealing with legacy code and applications.

In my opinion brownfield development is hard, and understudied. Every book on software development teaches how to develop a green field project, e.g. a project developed from scratch. Which is good. But no one is taught the essential skills and practices of brownfield development.

And that hurts. Very much.

What are the problems associated with brownfield development? They are many and varied and depend on both technical and human reasons:

• Lack of understanding on the underlying reasons why a technical solution was chooses to solve a particular problem.


• Lack of any legacy technical documentation and tests.


• Developers think they know the 'only right way' to develop software.


• Fear and uncertainty of breaking existing, working functionality.

When working on brownfield project I've found the following to be true and very helpful and productive:

Do not try to re-engineering the project when implementing new functionality, when the time comes that will be the only thing you will be doing. That way your will not bog down on useless, defect prone work.

• Do it as the other guy, use the same existing infrastructure and follow the same development principles. That way you will not add competing solutions and will achieve a homogeneous environment.



• Write a short, concise documentation for each feature you develop. That way everybody will know what you have done and why.



• Document key technical solution and practices in the project. Some problems and questions keep reappearing over and over. That way you will save everyone the time and effort of figuring them by them selves.



• Write smoke tests (functional or unit) for the core functionality of the project. That way you will always know if the core works or not.

The goal here is to not increase needlessly the complexity of the system, to save time and effort and to quickly gain the core knowledge the other guys had. If the client wanted you to re-engineer their system they would have hired you for that specific goal. It is often better to follow existing practices and procedures than to try to reinvent the wheel and fall in a bottomless pit of defects keeping popping up and deadlines never met.

Another day sprint

I'm concluding another day and a half development sprint. I started yesterday at five a.m. with a trip to Zagreb which lasted till six p.m. , filled with back to back blood grinding meetings. I've returned to Labin at eleven p.m. and started working on a deadline pressed project with three other developer. We've succesfully deployed the newest application version fifteen minutes ago. Another hour, and I'm crashing and burning into the nearest bed.

What lessons I've learned:

1. Writing at least functional, or just smoke, tests solves much development problems


2. Task development is half of well done feature


3. Regular standup meetings for tracking progresss and quick reactions to changes in the project situation


4. Wokrin in a virtual enviroment saves time and money, and increases the speed a new developer can join an undergoing project


5. Power naps help a lot

What is the motivation for doing a day and a half development sprint? For me is the challenge and the opportunity to be a hero, to save the day. To complete something hard and critical, which not many people can do. For others, I don't know exactly, but I recon is the same as me. I feel downright special right now.

Well I am special. so are my colleagues, we are a special team which completed something special. Nobody can take that away from us.

Sharing your knowledge

Why are developers, and people in general , so prone to entropy? Most of the software developers I know are really quick to throw aways good engineering practices in favor of writing more code. And use the same code writing exercise as an excuse of not doing those practices in the first place.
I have to much work to do! See, how many bugs I have to fix! What do I get from writing all these down, nobody will read that! Testing is stupid, I will be the only one doing it , everyone else doesn't do it!
Oh , how many such sentences I've heard from everyone I talked to. And the energy I spent correcting each and different attitude. Ah! And then to see them fall back to their evil no engineering ways, practically makes me wonder why do I try.
OK, I try , because I really want to teach others what I know and think that should be a practice for all experienced developers, only this way our profession will grow and evolve. I do not gain anything by not sharing and teaching others.
What are the benefits of sharing (for example with your team mates):

• You can shuffle boring and uninteresting work to them, while you focus on more challenging stuff



• You can discuss problems with someone who understands the topic , and possibly made some learning on their own



• You learn by teaching



• People around you will write code with greater quality

Teaching others , or sharing knowledge , has its drawbacks :

• Time spent teaching others is not time spent on improving you


• Teaching others (in my experience) often diminishes your knowledge in the eyes of others , since for them is so easily gained


• Teaching is a strenuous and continuous process with unknown results (if you want to see big bangs for you bucks quickly, better be ready for disappointment)

And the greatest truth of all: you can't force people to really learn and implement that they are not interested in. Especially if you do not a rifle on their heads.

Back to work

'm nervous, really nervous. For the last two weeks I was at home, resting and relaxing on my hard earned holiday. These were the first totally relaxed two weeks of holiday in , I think, more then five years. And now, today, I'm going back to work. And I'm so nervous. Really.

For the past two weeks I haven't studied anything related to the field of Software Engineering. Instead I spent my time with my son Sven and my wife Tijana, I read fantasy novels (Steven Erikson “The Bonehunters”) and prepared a 4E D&D quest for my wife and our two friends. In short I was a lazy bug in all. Now is time to go to work and enter the grinding machine of stress, constant learning, long hours and impossible deadlines (no deadline is impossible, it is just impossible what you want to do in that time span with the resources you have).

How do I cope with this emotion? Well I woke early, I restarted my morning pilates exercises, opened a DNR TV video for Windows Workflow Foundation. During lunch break I will read “Software Engineering” 8th edition, and will begin a new practicing advanced ASP.NET 3.5 in hopes of one day continue with WCF, WPF and F#.

Will I succeed? Will I be my old self and continue my work as usual? Or will I fall victim to laziness and the eternal question: Which is best, fighter or wizard?