maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian Ewins <>
Subject Re: OT: codebase design guidelines - Happy Holidays!
Date Tue, 24 Dec 2002 11:43:20 GMT
Interesting doc. I've got some specific and general comments; most of 
the specific bits could be summed up by 'rules have exceptions', though.

"# all classes  must follow a premeditated package dependency strategy
     * strategy shall be enforced by the build process"

A good way to do this is to build things which are meant to be 
independent as separate jars. Probably not coincidentally, in my 
experience maven lends itself best to smaller jars, and then building 
the main project from these subproject jars.

"code-internal constants ... shall always  be declared in 
typesafe-enumeration style classes"

well you do know there are issues with deserialization of typesafe 
enums? ( deser(ser(A))!=A )

"all XML messages and parsers shall use an appropriate XML Schema 
document for conformance validation"

Well that rules out maven.xml then ;). Seriously, there are a lot of 
situations where schemas are a Bad Thing, and even when you do have 
schema, there's the whole WXS/RELAX-NG argument over whether strict 
typing is always a good thing. (see the xml-deviant columns on 
for the arguments).

"# filter enable reuse...separated by target system configuration"

This is a 'build smell'. You're describing a process to support separate 
builds per target system. How are you testing all of these builds?

To scale up delivery to many, many target systems, you need to have 
builds which are configured after they are installed, not while they are 
being built. This means that the build on all installations is exactly 
the same one you tested. It also helps you plan to stop configuration 
changes made onsite from being overwritten during an upgrade.

"intermediate results of build steps shall be stored within a directory 
structure under /work"

How do you distinguish 'intermediate' from 'final' results? You describe 
'target/classes', when the classes are usually intermediate to building 
the jar. Don't ask people to distinguish the indistinguishable. To 
answer my own question - project deliverables are the only things you 
make which are clearly distinguishable from the intermediates (usually a 
jar, war, zip, or installer). Those /are/ things you should separate out.

"a file called base-project.xml..."

This guideline only makes sense if you've already written a build script 
that works this way - and I'll bet that it won't be the last word in 
project structures. So this more properly belongs in a set of 
instructions for using your specific build system, and the indefinite 
article shouldn't be used: "The file called base-project.xml ....". 
Theres several other bits like this in your doc; I think these confuse 
the requirements (good code management) with the implementation (a 
specific build process). This stuff all needs documented, but separately.

"no code formatting specification shall be enforced..."

Eh no, this is a nightmare when working in teams. Its also a bit silly 
when we have tools like jalopy available, but I do agree that simply 
reporting a lot of minor style errors with tools is not greatly helpful. 
Take a look at one of my bug reports on maven:

this gives you a style for checkstyle that won't report errors on 
anything jalopy can automatically fix. Its then up to you to use jalopy 
to keep things legible.

More generally: when writing coding/design guidelines in the past I've 
found it helpful to distinguish:
1. things that a tool can fix
2. things that a tool can check
3. things that a human can check
4. things that can't be checked.

Try to move everything in your guidelines as far up this chain as 
possible. Document (1) and (2) separately, make the tools part of your 
process, and don't expect people to remember all the rules; they won't, 
but the tool will point out when they break them. (3) forms your main 
guidelines document, because its the only one where you rely on people 
to actually remember and check things. So keep it separate and short, 
there's more chance people will be able to remember it all[1]. (4) is a 
list of all the things you need to think through better before you ask 
people to do them ;)

I commented at the start that rules are made to be broken. It is ok to 
write rules which you will allow to be broken as long as you provide an 
extra rule for this:
- Any of these rules may be broken if there is a justifiable reason to 
do so. The reason must be documented (if the breach is in code, as a 

Finally, always provide blank/sample/template projects so its easy for 
devs to start out in the right direction.

(Merry Christmas!)

[1] For example, in one of my employers we had the Ellemtell C++ 
guidelines (80+ pages?), Java guidelines intended to be slimmer than the 
C++ ones (Sun's plus our own; 35 pages IIRC), and perl guidelines 
written along the lines described above. The bit you had to remember was 
2 pages long. Guess which guidelines got followed :)

John Casey wrote:
> I just thought I'd toss something out for a little light reading this
> holiday season.  I'm trying to compile all that I've learned over the
> past few years on the nitty-gritty side of project management - codebase
> management.  What I'm trying to nail down is the "correct" way to design
> a project so that it is manageable, usable to new developers, plugs into
> continuous integration tools, etc...
> Anyway, if you have time, I'd love any feedback I can get.
> I already know that I've forgotten to include a section on testing...I'm
> working on that.
> Cheers,
> John
> --
> To unsubscribe, e-mail:   <>
> For additional commands, e-mail: <>

View raw message