Return-Path: Mailing-List: contact turbine-maven-user-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list turbine-maven-user@jakarta.apache.org Received: (qmail 11417 invoked by uid 98); 24 Dec 2002 11:51:37 -0000 X-Antivirus: nagoya (v4218 created Aug 14 2002) Received: (qmail 11398 invoked from network); 24 Dec 2002 11:51:35 -0000 Received: from daedalus.apache.org (HELO apache.org) (63.251.56.142) by nagoya.betaversion.org with SMTP; 24 Dec 2002 11:51:35 -0000 Received: (qmail 57796 invoked by uid 500); 24 Dec 2002 11:50:24 -0000 Received: (qmail 57789 invoked from network); 24 Dec 2002 11:50:23 -0000 Received: from mail.i-documentsystems.com (HELO web1.i-documentsystems.com) (213.105.192.33) by daedalus.apache.org with SMTP; 24 Dec 2002 11:50:23 -0000 Message-ID: <3E084858.4080101@btinternet.com> Date: Tue, 24 Dec 2002 11:43:20 +0000 From: Brian Ewins MIME-Version: 1.0 To: Turbine Maven Users List Subject: Re: OT: codebase design guidelines - Happy Holidays! References: <3E06EC78.5030902@btinternet.com> <1040685148.14539.6.camel@dream.nts.ku.edu> In-Reply-To: <1040685148.14539.6.camel@dream.nts.ku.edu> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 xml.com for the arguments). "# filter sets...to 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: http://jira.werken.com/secure/ViewIssue.jspa?key=MAVEN-159 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 comment). Finally, always provide blank/sample/template projects so its easy for devs to start out in the right direction. Cheers, Baz (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. > > http://www.commonjava.org/strategy.html > > 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: > >