12 January 2009

How source code should not be organized

I'm a bit fascinated on how source code are organized in a repository. There are certainly different ways of doing it and there are many ways that are wrong, or at least clumsy. Here are some examples that I have seen in real life and hope that you don't make the same mistake.

The root as the java package root.
That is if you have a class named com.mycompany.MyClass the structure is
Why is this wrong? This is ok if your repository only contains java source code. But I have never seen this happen. A repository always contain other files (build scriptes, resources, source code from other language etc). Putting the java pacakges root as the folder root will cause problem with include/exclude filters in build scripts and IDE:s. It will also make submodules hard to implement.

A better way is to put the source code in a dedicated directory. For example:
/src/java/main/ or just /src/main if you are absolutly sure that java is the programming language. So why not just /src? Well mainly becouse there are different types of source code. There are production source code, test source code and possibly more types. Even if you are only programming java there is justification for the /src/java/main, sometimes you will for example need to include java-like things (for example Google Web Toolkit is almost java, but not built the same).

Dependencies between modules not exposed in a development environment
Lets say you have your main module A. One of the developers begins to develop module B depenent of module A in a seperate repository path and not exposing this in a development environment. Developers in module A will not see the dependecies to module B. A change in module A could break module B without anyone knowing.

A better way is to have common workspace base containing both module A and B. this way all developers will check out all code and developers will get faster feedback. Maven has native support for this type of modularisation (and submodularisation).

No comments:

Post a Comment