Don't just put your documentation in source control

In the GS04 course at UCL I told the students to put everything into source control; not just source code but also things like documentation and configuration files.

That's all very well, but my current project at work has made me realise that you can do even better. You should not just put your documentation in source control, you should serve it from source control.

On my current project we have all our documentation served directly from our subversion repository, mostly as html.

What about Wikis?

I used to be a big fan of having a project wiki.

A wiki can be great but:

1. they do have a tendency to get out of date easily
2. they can accumulate lots of garbage
3. they can be difficult to version control well (difficult to keep in sync with the project's source code repository - I know there are things like Trac but in a lot of companies you don't get to choose what systems you use)
4. if the project is abandoned for a long time, the chances are that the wiki might disappear (I've seen it a few times - moving to another wiki system and not migrating old pages) but the source code repository will be around for a long time (and if it isn't then you're screwed anyway).

Wikis still have their place - when collaboration with lots of people is needed, but for developer written documentation I'm happier to have it in the same source control system as the code it refers to.

Taking my own advice

I've updated my semi-abandoned project build-o-matic, so its web site is now served directly from its source code repository. It's now so much easier to update the web site (just edit and commit) that I might even get the web site up-to-date.

But there again, the World Cup is on TV today ...

Copyright © 2010 Ivan Moore

throw null

My colleagues told me of some code they came across which included the statement: "throw null".

I'd never seen that before - I didn't know what it would do or even if it was valid.

I'll let you think about it. Have a go if you want to check your answer:

public class Surprise {
    public static void main(String[] args) {
        throw null;
    }
}

Copyright © 2010 Ivan Moore

Tools and Environments - SCM and CI

When I taught source control and continuous integration in 2007 (for the GS04 course at UCL) I used Subversion for the source control lab and build-o-matic for the continuous integration lab.

In the labs this year, I'll be using Mercurial instead of Subversion, and Hudson instead of build-o-matic.

What would you choose for teaching source control and continuous integration (and for bonus marks, why)?

Copyright © 2009 Ivan Moore

Tools and Environments

Steve Freeman and I are teaching a course at UCL called "Tools and Environments".
The course we wish we’d had in college, only we didn’t know it at the time.

We cover subjects such as source control systems, automated builds, automated testing and continuous integration.

In preparing for the course, I've been reminded of how few books there are which we can use as a "course text". There are plenty of books for specific tools (e.g. Ant) once you know that you need those tools, but few books which explain the sorts of things that you need for real software development projects, and why you need them.

The book we're using for our "course text" is Practical Development Environments (and we'll also be recommending Continuous Integration as that also covers much of the material of the course).

If you have other recommendations please add a comment!

Copyright © 2009 Ivan Moore

Three heresies

I encourage people to think for themselves rather than following cargo cults. You might or might not agree with the three heresies I've written about here, but do at least think about them.

Public fields

In Java code, instead of having a public getter and public setter for a field, why not just make the field public? It's much simpler and less code. If you later need a getter and setter for some reason you can always refactor to that (and many IDEs will give you help doing it). There is a comment by Richard Gomes at the end of this previous article on the subject of public fields for data objects. I think public fields make most sense for NOJOs (data objects) (in the rare case where a NOJO is useful - not very often) but maybe it would sometimes make sense for other sorts of classes too?

Note that having public access to a field is not what I'm trying to encourage. The point I'm making is that if you do have public access to a field then it doesn't matter much whether it is by getter/setter or making the field public, so you might as well use a public field as it is simpler. (But please, tell don't ask instead.)

Magic values instead of constants (in build files)

Instead of always factoring out magic values as properties in your build file, consider just using the magic value where it makes sense. For example, maybe instead of "${src}" just use "src" (and get rid of the property) - this was suggested by Jeffrey Fredrick at CITCON Paris 2009. I think there is a lot of merit in this approach. What are the chances that you'd be able to just modify the value of the "src" property and everything would still work? Probably quite low - you'd probably do a text file search for "src" anyway. What are the chances that you'll want to change it anyway? I think it's worth thinking about whether it's better or worse to factor out constants in some cases.

Make the CI build fail fast rather than run all the tests

Rather than running all the tests in your CI build, how about have the build fail as soon as any test fails? That way, a failing build uses less of your build farm's capacity. If your build farm capacity is limited, then this approach may result in getting a passing build sooner (as when the fix is committed there may be a build agent available for running the build with that commit sooner because it's time isn't being taken running a build which will eventually fail anyway). I think it's often more important to know which commit broke the build than which tests failed in order to know both who should fix the build and what caused the build breakage. This approach might not be so good if you have a flickering build (i.e. randomly failing tests) - however, making the build reliable can be achieved and is worthwhile anyway.

More heresies to follow

I have other heresies to write about. Please suggest your own in the comments.

Copyright © 2009 Ivan Moore

Java Enums with constant-specific methods

One of my colleagues introduced me to this handy language feature of Java 1.5 and I wanted to write an article about it because I hadn't seen this before.

Using google reveals that it is already well documented if you RTFM, but I will repeat it here because talking to other Java developers indicates that it isn't as well known as it deserves to be. Here's a slightly reworded extract from the first hit on google or bing for "java enum":

You can declare abstract methods in an enum and override them with a concrete method in each constant. Such methods are known as constant-specific methods. Here is an example using this technique:

public enum Operation {
  PLUS   { double eval(double x, double y) { return x + y; } },
  MINUS  { double eval(double x, double y) { return x - y; } },
  TIMES  { double eval(double x, double y) { return x * y; } },
  DIVIDE { double eval(double x, double y) { return x / y; } };

  // Do arithmetic op represented by this constant
  abstract double eval(double x, double y);
}

Copyright © 2009 Ivan Moore

New version of Jester released

It's been a while since I last updated Jester (a mutation testing tool).

Today I released a new version of Jester - not much changed - but hopefully a bit easier to get it to work, based on my experiences of trying to use Jester when I haven't tried for a while.

It now doesn't read configuration files from the classpath - instead you specify the relevant files on the command line.

Copyright © 2009 Ivan Moore