My Coding Rules

The following are just my guidlines for writing good code. The advise here may be scattered at best contradictary at worst. I write primarily java so I guess that this advise will just reflect my current feelings on java like code.

What I think changes from time to time.

Everything should have one purpose.

This is pretty important everything should have one purpose and only one purpose.

Write code with this in mind always naturally its tempting to think I’m talking about classes here but in reality this extends to much more than classes.

Methods

Methods are a prime example. I often see code that looks like this.

public Response execute(params) {
    // iterate over the all
    // validate each one.
    // find one parameter that you need to do something special with.
    // Call an upstream service.
    // validate the response from the call.
    // finish iterating.
    // do a calcuation on the result.
    // if a result contains a certain value return
    // process the rest of the result
    // return a response.
}

Now theres nothing wrong with any of those steps in themselves. However what you end up with is a tangled mess of operations that are extremely difficult to do any refactoring to and is also difficult to test. How do you validate that your delegating to the upstream service correctly from tests? The answer is you simply don’t.

Now the first thing you should so is seperate the block into seperate methods, making sure each method has a descriptive name. This instantly brings up the readablity.

However even with that approach its still difficult to test. You can either make the methods protected for the sake of the tests. Or more likely ask yourself is the class itself doing too much? Validating an object and doing business processing are two seperate concerns. Ideally you want the business logic in a completely seperate class without the confusion of anything that isn’t a buisness rule. The business classes are really what your application is about in the end of the day and must be clean.

Classes

I won’t go into classes too much. There are already umpteen different rules to remember with classes, and some old tricks such as fitting everything that they do into one index card. What a will suggest is that what the class does or its responsiblities should be commented at the top of the class.

example

package com.wesley_acheson;

// Responsible for calculating the tax 
// Based on the country
// 
// delegates to CustomerInformationService to find out information about the customer.
public class TaxCalculator {
 
    private CustomerInformationService upstreamService;

    public TaxCalculator(CustomerInformationService upstreamService) {
        this.customerInformationService = upstreamService;
    }

    public InvoiceEntry calculateBatchTax(OrderBatch batch, Customer customer) {
        //Do some logic here.
        //Don't forget to split the method up.
    }

    // Note that even though this just delegates to another call
    // Its really saying this is the part of the Customer service
    // that is of intrest to me as a Tax Calculator.
    private TaxRates getTaxRateForCustomer(Customer customer) {
        return upstreamService.getTaxRates(customer);
    }

}

Packages

Packages are the most abused concept that I see. Most times when I look through a code base people are splitting their packages as follows.

  com.example.servlets
  com.example.services
  com.example.dao
  com.example.entity

The problem with this is manyfold.

  • Firstly try to make some of your internal methods have package level protection. This always breaks as it isn’t available.
  • Secondly its hard to trace the flow of information arround so many different packages.
  • Generating a diagram of a packages uses is difficult

The solution is simple. Keep objects that need to refer to each other to the same package. I’d much rather see people suffexing their classes with what the class is rather than split by package on arbitary lines.

The amount of packages you will need tends to vary with the complexity of your application. Try starting with one or two base packages first. Then as complexity grows move objects that aren’t related out.

Now this isn’t enforced by the java compiler but I like to see classes that are used alot in parent packages of the packages that call them. Thats personal taste however and if you perfer to put your util classes in a package called util then go for it.

One place that a package for all the objects may be a good idea is if following domain driven design then by all means put your domain objects in one package. I warned you my advise may be contradictary. The simple reason for that is if you have a well thought out domain model its probably better to see the relationships with that then splitting on other criteria.

Note I’d probably keep TaxRates and TaxCalculator In the same package. If I had a need for them. I’d also keep TaxDao and TaxService in the same place.

Duplication

It should be the aim of every programmer to keep code duplication to a minimum at all points. Copy paste is evil and you will get tripped up by it sooner rather than later.

The problem with copy and paste is its often the quickest way to achieve the desired result. However If you find a bug in one copy of a method and think there may be 50 derivatives what are you going to do?

This is getting long and windy I’m getting tired. I guess I should finish or cleanup on another day. Love to hear from you all what your opinions are.

Window Java Build server

Creating a Java build server on windows

Technologies used.

SVN – Version Control.

Apache httpd server – Serve contents

Java – Required to build java projects (duh), needed by nexus, tomcat and maven.

Tomcat – Required to run Hudson (note Hudson will work on other application containers, tomcat is my container of choice)

mod_jk – Maps apache to tomcat etc. Note again there are other ways of doing this.

Hudson – Kicks off maven builds and deploys to maven.

Nexus – Binary repository manager

Trac – ticket system and repository browser

python – required by trac

Mod WSGI – required to map python to Apache.

Chosing an install directory.

It simplifies maintaince if all the applications can be installed to the same place. For the purposes of this post I’m going to install to a folder under c:/services.

Stopping IIS

IIS was currently running on the server. To stop IIS I went to the command prompt and types iisreset /stop followed by iisreset /disable.

Then go to services and disable the IIS Admin Service.

Installing Apache httpd

For this I’m going to download the latest apache server. At time of writing the latest server is 2.2.16. We are going to chose the win32 binaries because thats what are available on Apache and if we run into problems we are more likely to see other people with the same problems.

Choosing the Open SSL version as thats easier.

Binaries can be found at http://httpd.apache.org/download.cgi

Stepping through the installation steps until the point of Network Domain is reached.  For the network domain I’ve chosen [mycompaniesdomain].com

server name will be build.[mycompaniesdomain].com

Email address my work email address.

Chose for all users on port 80 (The recommended setting).

I’m going to choose a custom installation as I wish to chose an install directory.

Choose not to install the documentation as the documentation on Apache.org is sufficient. I’ve opted to include the Build Headers and Libaries in case we ever need to compile something against this apache.

Remove APR Iconv Code Pages as its not required.

Choose the root option “Apache HTTP Server 2.2.16” and change the install location to your install directory. c:\services\apache\

Okay now to test the configuration.  We just want to be sure it launches we can harden the server later.  From the start menu under apache choose “Test Configuration”. This opens up a window with some text which just flashes up and disappears.

I get the following error:

C:\>c:\services\apache\bin\httpd.exe -t
httpd.exe: Could not reliably determine the server's fully qualified domain name
, using 10.10.14.3 for ServerName
Syntax OK

Okay this is fixable. Basically I need to change the definition of server name in httpd.conf c:\services\apache\conf\httpd.conf

Looking in httpd.conf I see the following lines.

# ServerName gives the name and port that the server uses to identify itself.
# This can often be determined automatically, but we recommend you specify
# it explicitly to prevent problems during startup.
#
# If your host doesn't have a registered DNS name, enter its IP address here.
#
#ServerName build.myriadpayments.com:80

We need to uncomment the ServerName entry.

rerunning the test gives Syntax okay.

Finally to start apache we run the following command c:\services\apache\bin\httpd -k start

If it starts navigate to localhost and ensure you are seeing contents. I see “It works!” which supprisingly means it works 🙂

Python

Python is needed for trac.  Lets get on and install that next.

Python can be downloaded from http://www.python.org/download/ . Trac utilises python 2 so we will give python 2 a go.

At the time of writing python (2) is at version 2.7 Thats the version we are going to get. Also as there are a few issues surrounding the 64 bit version and it needs to match the apache version. We are going to choose the 32 bit version.  Python 2.7 Windows installer

Choose install for all users. The default install directory is c:\Python27\ but we are going to change that to c:\services\Python27\

Going for a complete install here basically choose all features and install.

With a bit of luck python now works.

Subversion

Download a version of subversion. I’ve chosen the silksvn binaries avaliable from http://www.slik.com/en/download.

Connecting to apache.

Easy Install

Easy install is a python script that makes updating other python scripts easier. It can be found at http://peak.telecommunity.com/dist/ez_setup.py

Run the script in python.

C:\services\Python27\Tools\Scripts>\services\Python27\python.exe ez_setup.py

This installs setuptools

MOD_WSGI

Mod_WSGI can be found at http://code.google.com/p/modwsgi/ you need to choose an appropiate one for your version of python and your version of apache. In our case it will be mod_wsgi-win32-ap22py27-3.3.so – Apache 2.2 / Python 2.7

Copy to c:\services\apache\modules. Rename the module to mod_wsgi.so

Add

LoadModule wsgi_module modules/mod_wsgi.so to apache conf and restart

trac

In the c:\services\Python27\scripts run easy_install trac. This should install trac. Next we need to setup a trac repoisitory. In the same directory run trac-admin.exe c:\services\trac initenv. You will be asked a few questions.  Enter the values you want. For database you can just use the default.

The next step is to deploy the trac creation script to a new document root for trac. I’ve chosen c:\services\trac_www as the web root for trac.

trac-admin.exe c:\services\trac deploy c:\services\trac_www

Mapping trac to apache

Find the wsgi file created by the above script. On my computer this is in c:\services\trac_www\cgi-bin

Add the following to your httpd.conf

WSGIScriptAlias /trac c:/services/trac_www/cgi-bin/trac.wsgi

<Directory c:/httpd/www/trac>
WSGIApplicationGroup %{GLOBAL}
Order deny,allow
Allow from all
</Directory>

Test in apache now. On the same machine as you are viewing go to http://localhost/trac/ . If you have a forbidden message it may be because permission is removed from directories.

in you httpd.conf find the following

<Directory />
Options FollowSymLinks
AllowOverride None
Order deny,allow
Deny from all
</Directory>

Change this to

<Directory />
Options FollowSymLinks
AllowOverride None
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Directory>

And restart apache “c:\services\apache\bin\httpd -k restart”

Try again.

With any luck you should now see trac installed.

Maven

Download maven as a zip file. Inside you should see a folder called “apache-maven-2.x.x” copy this folder to wherever you want maven isntalled.

In our case this creates a folder called c:\services\apache-maven-2.x.x\

Add maven to the command line.

Tomcat

Download windows installer service. Install using the defaults.

Remove HTTP connector. Remove all comments from server.xml

Add a worker.properties file with the following contents in the apache conf directory.

# Define 1 real worker using ajp13
worker.list=worker1
# Set properties for worker1 (ajp13)
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009

Add the following directives to apache

JkWorkersFile c:/services/apache/conf/worker.properties
JKLogFile c:/services/apache/logs/jk_log.log
JKLogLevel info
JKMount /manager* worker1

Download Hudson.

Hudson can be downloaded from http://hudson-ci.org/latest/hudson.war

Set the following environement variables

HUDSON_HOME =  c:\services\work\

copy the hudson war into your tomcat webapps directory.

Add a mount argument so requests to /hudson are passed to the worker.

JKMount /hudson* worker1

At this point you should restart apache and tomcat to ensure its all working. Hudson requires UTF-8 Urls so in your server.xml you should put URIEncoding=”UTF-8″

Saturday Morning Churros

On Saturday mornings I often take Connor into the square in town for Churros. Churros are a Spanish type of batter which they eat as breakfast. These are taken the same day as “blurry”

Anyway he loves them. I don’t want to forget how excited he gets about them. Once they arrive he really digs in. This Saturday he ate nearly a whole plate of them himself. It was a good morning. Nice and warm in the sun. Sitting there drinking my coffee. He was alternating between his Churros and a glass of pineapple juice.

I even managed to get a couple of shots in.

He really enjoyes these Churros. I know that It looks like a dainty bite but believe me its not.
Connor enjoying Churros in Casemates.
Connor doing his crazy act.

Blurry

Blurry

Thats not something you want your photos to be or is it.

This morning I was out with Connor my son. And I deliberately took a blurry photograph of him. I was trying to do something different you know. So he was out of focus in the background.

I couldn’t get him to look up which is a shame but anyway by pure coincidence when I checked out a site I’ve been visiting recently http://digital-photography-school.com and this was one of the new pages.

So I thought I’d put the photo up here and enter it as a submission. So there you go.

Does it work? I’ve no idea but I find it interesting and I think that’s probably good enough at the moment. So without further ado.

Appreciation for distance.
Appreciation for distance.

Anyway let me know what you think I’d love to hear from you.

New Lunar Image

Okay so I’ve been out photographing the moon again. I tried at two seperate times tonight. The first time went quite well so I was pleased with that. However I felt the focus could have been a bit better on the subject. The second time I went out with more or less the same settings however I tried to manually focus on the moon.

It all looked great through the view finder so I set the exposure compensation to -2 stops (the minimum on my camera) and the exposure bracketing to +-2. So basically that was one photo at -4 one at -2 and one at 0. However disaster even with these settings when I clicked the shutter It was over exposing the image. (I took 50 shots and verified on the computer but not even one of them was properly exposed). Looking at the EXIF data they were a lot slower than the origional shots so what am I doing wrong? I’m not sure what metering mode my camera was in. Update: I just turned it on now and it was in partial metering mode.

Is it because the sky was lighter in my original shots that the camera chose a different time for the shots one which gave good exposure? Indeed I took the photograph when the sky was still blue. (but not very blue). How do I get decent exposure?

Anyway here is my favourite attempt from the first shoot. I’ve had to increase sharpness in raw mode and also add back in some brightness.Hey its the moon.

If anyone would tell me how to get correct exposure I’d be grateful.

More Camera Fun

In my first post about getting a DSLR camera. I promised that I’d put up a few examples of pictures that I wouldn’t have attempted to take if I was using a film camera.  So I guess I really should, so here they are.

Okay first up is an HDR image of Ocean Village Gibraltar.  HDR images may have been possible before but digital but if they were they would have been really difficult.  Basically taken using three shots one light one dark and one normal.  These are then combined in the computer.  I like the cold feel to it and the unnatural look.

Ocean Village Gibraltar

Secondly we have an Image of the Moon. I really like the way it came out composition wise but I’m still trying to get a final edit of this one that shows the detail of the moon very clearly.  I ended up taking over 100 shots with my camera with a 300mm lens at full zoom to try to get this photograph.  The reason it took so many is I was trying to hold the camera steady by hand. Anyone who has used one of these lenses will tell you thats not an easy prospect.

To get any image at all I needed to turn the camera up to its highest ISO so the shot was taken quickly.  ISO is basically the sensitivity to light.  Unfortunately this has brought up a lot of noise.  I hope on a later date to be able to fix this on up to the point where I’m happy with it.

Moon rising behind tower.

The next one I’ve taken twice with two very different effects applied in Post processing. They are pictures of my eye. Yes I took a photograph of my eye. This certainly felt stupid. Thank goodness for auto focus on the camera :p.

I hope that nobody finds a way to turn this into an iris scan.
My Eye

Finally you can see I’ve also been experimenting with black and white.  I’m pretty pleased with this shot.

A night time image of the top of a building.

Anyway there you have it.

A decent tutorial for HDR can be found at http://www.stuckincustoms.com/hdr-tutorial/ however I find the article itself to be a bit spammy.  There are wonderful examples on this page and the pages that follow however.

I didn’t us this I just used Paint Shop pro X however for my pictures.  I’ve seen some good video tutorials for this on youtube but I can’t find them right at the moment.

You can read more about ISO over at wikipedia.

The last link I’ll leave you with explains Post Processing.

So as you can all see I’m really having fun at the moment.

New DSLR camera.

Over Christmas I was given a DSLR Camera. This is something that I have wanted for quite a while. I used a SLR camera in the past and although I really liked the photographs that I took with it, they were just snapshots.  I mean I just took the standard things, pictures of my family etc, in automatic mode. I couldn’t learn how to use the camera properly because well it just wasn’t possible to experiment without taking rolls and rolls of film and getting that developed.

I’m much happier with the new situation, I’ve taken over 800 photographs since Christmas day.  Most are not good In fact I would go so far to say that a much smaller percentage of them are keepers but that’s just because I couldn’t take risks in the past. I’ve got some things together that I don’t know that I’d ever have tried before and I’ve had a lot of fun doing it.

I do want to get better though.  I really do, a college of mine at work is also very interested in getting a DSLR.  Sure its going to be more expensive than mine and I’ll probably be jealous but its going to be great to have someone to talk to who’s also sharing the same interests. He’s primarily interested in long exposures as far as I can tell. Anyway he sent me a link to Digital Photography School which I think has some wonderful learning resources on it. To be honest he just sent me a link to some wonderful examples of long exposures. http://digital-photography-school.com/long-exposure-photography

Anyway that’s pretty much it for the moment.  I’m going to post a couple of examples of photographs that I’ve taken that I wouldn’t have taken before later.  Don’t be too critical I’m just learning.