Project Kit List

Essential Items for Software Projects

A recent conversation with a friend made me realise that things I have come to think of as standard practice for software projects are by no means universal and that problems I had thought not relevant any more are still around and causing mayhem and chaos around the world for developers and managers alike.

So casting caution to the wind I thought I would draw up a list of things I find essential for a project

• Version Control


• Build server


• Wiki


• Issue tracking


• Text Editor

Version Control

It is difficult to understand why any project would not use version control. No decision is final and no PC or server is 100% reliable. At the very least Version Control is a personal safety net for things that can and will go wrong

I like to take things a little further and make version control the only way of communicating changes to the build server. This ensures that everything is under version control and that those little change that I will remember forever (hah) are written down somewhere. (The build server config should also be in version control - makes rebuilding a build server a breeze)

My personal preference is subversion. Its free, open source and works really really well. If you are using a version control system with features not supported by subversion think seriously about whether you really need those features. No really many version control systems have features that promote complex processes and practices that can really get in the way.

Build Server

My second essential item of kit is a build server. Hardware is now so inexpensive that there are few excuses for not having one of these

If you cannot afford an additional server or it is not practical (on the road with a laptop perhaps) then invest in a good virtualisation system had run your build server on the same hardware or one of the dev boxes if you are working in a team.

Wiki

If you are working in a team or even by yourself using a wiki to record things as the project goes along is great. Especially if your memory is anything like mine. Wikis are especially useful if you need to share information about the project or team with people out of your office.

Wiki's such as track also have a bug tracking system built in and integrate with a subversion version control

Issue Tracking

As your code base matures you are going to need something to keep track of the problems and changes that people want.

Don't go overboard. Putting too much reliance on an issue tracking system is that same as code generators and wizards in your ide - they stop you thinking about the problem and generate a lot of noise

Having said that I am a great fan of code generators :)

Text Editor

Ok so why put a text editor in the same rankings as version control wikis and such?

I am with the Pragmatic Programmers on this one. Having a good text editor to call upon is essential. By good I mean it fits your work, you and the things you need do do. But like all good tools you need to spend time with it learning what it is good at. My personal choices are TextMate on the Mac and Emacs just about everywhere.

---

Best Practice

Ok now the preachy bit. But as with tools make sure you need the practice before you use it. I have seen project adopt practices because they have seen them work well on other projects without considering the impact or relevance to the current project. Having said that some things really are universal.

Build servers and pipelines

I have talked a bit about having a build server. If you hav'nt got one look into getting one.

If you have one then there are some additional things you should consider.

• Everything on the server came through version control. Ok maybe everything is a bit steep. Your going to need an OS, runtime and build software and other stuff that is just not practical to put through version control. But perhaps scripting the intallation and putting that script in version control would work. It would certainly make it easier to set up another build box.


• Everything going to production comes from a build server. Yep no more quick file deployes and patches from dev boxes. If it is important enough to put through testing it is important enough to have traceability through the build.

In some situations one build server is not enough. Perhaps you are maintaining multiple versions of the application or there are complex integration points that are tested as part of a different build. (It is often useful to have a fast developer build to provide rapid feedback to the developers and then a longer integration build that makes sure the application works in its intended envioronment.)

Integration builds

Having mentioned Integraion builds I had better expand on what I mean by integration builds and integration as a concept

Integration and Continuous Integration (CI) (as part of build systems such as CruiseControl CruiseControl.net etc) are talked about a lot but what does this mean in practice and how best to make use of these tools.

The word integration and continuous integration covers a lot of concepts. Perhpas the first level of integration and I believe the original intent for work integration of the changes made by eack developer in the team.

Managing session state in persitent objects

On my current web project, like most web projects, needed a way of managing user session state. We wanted a clean separation from the web tier and a way of managing warnings or annotations to the supplied user data incase the data was not valid.

We decided to store information supplied in a GET or POST request in document objects. These document objects would then be used by the service tiers to perform the requested operation. Each document object was kept simple by only allowing fields/attributes. The documents would be validated by a validator for each document type, the validators using a utiltity class of validations to keep the duplicate code count low. The documents can be presisted for long running user transactions.

Perhaps the best way to illustrate how this works is with an example. Lets assume that we have a request handler for a registration service that takes a map of name/value pairs for the values the user has supplied on the registration form. For simpliity the response and error handling paths have been ignored.

import java.util.Map; 
 
public class RegisterRequestHandler { 
    private RegistrationService registrationService; 
 
    public RegisterRequestHandler(RegistrationService registrationService) { 
 
        this.registrationService = registrationService; 
    } 
 
    public void handlePost(Map<String, String> params) { 
        RegisterDocument document = readDocument(params); 
 
        RegisterDocumentValidator validator = new RegisterDocumentValidator(); 
 
        if (validator.validate(document)) { 
            registrationService.register(document); 
            redirectToSuccessfulConfirmation(); 
        } else { 
            persistDocument(document); 
            redirectToRegisterPath(); 
        } 
 
    } 
 
    private void redirectToSuccessfulConfirmation() { 
        // ... 
    } 
 
    private void persistDocument(RegisterDocument document) { 
        // ... 
    } 
 
    private void redirectToRegisterPath() { 
        // ... 
    } 
 
    private RegisterDocument readDocument(Map<String, String> params) { 
        RegisterDocument registerDocument = new RegisterDocument(); 
        registerDocument.name = new Field(params.get("name")); 
        registerDocument.password = new Field(params.get("password")); 
        registerDocument.userName = new Field(params.get("username")); 
 
        return registerDocument; 
    } 
} 

The handlePost entry point turns the name/value pair of parameters into a registraion document representing the users application for an account. The document is validated and if valid a request for a new account is passed on the appropriate service. If the document is not valid the user is redirected to the registraion application form with any warnings identified int he persisted registrtion document.

The registration document contains the fields we expect from the UI and very simple helper methods.

public class RegisterDocument { 
    Field userName; 
    Field password; 
    Field name; 
 
    public boolean hasWarning() { 
        return userName.hasWarning() || password.hasWarning() || name.hasWarning(); 
    } 
} 

The field class manages the value and any warnings.

public class Field { 
    private String value; 
    private Annotation annotation; 
 
    public Field(String value, Annotation annotation) { 
        this.value = value; 
        this.annotation = annotation; 
    } 
 
    public Field(String value) { 
        this(value, Annotation.none); 
    } 
 
    public String getValue() { 
        return value; 
    } 
 
    public void addWarning(String warning) { 
        annotation = new Annotation(warning, Annotation.AnnotationType.warning); 
    } 
 
    public boolean hasWarning() { 
        return annotation.getType() == Annotation.AnnotationType.warning; 
    } 
} 

Perhpas choosing the most overloaded name (Annotation) this class models the validators response. Allowing warnings or infomation to be associated with the value. Used to report problems back to the user.

public class Annotation { 
    enum AnnotationType { 
        warning, info, none 
    } 
 
    private AnnotationType type; 
    private String value; 
 
    public static Annotation none = new Annotation("", AnnotationType.none); 
 
    public Annotation(String value, AnnotationType type) { 
        this.value = value; 
        this.type = type; 
    } 
 
 
    public AnnotationType getType() { 
        return type; 
    } 
} 

public class RegisterDocumentValidator { 
    public boolean validate(RegisterDocument document) { 
        if (isEmpty(document.name.getValue())) { 
            document.name.addWarning("You must supply a name"); 
        } 
 
        // ... 
 
        return document.hasWarning(); 
    } 
 
    private boolean isEmpty(String name) { 
        return (name == null || name.length() == 0); 
    } 
} 

Any services use the documents as parameters. They are decoupled from the UI and can be more easily unit tested.

public interface RegistrationService { 
    void register(RegisterDocument document); 
}