This is great! Thanks for the feedback, this is exactly what I needed. BTW, is there a good book, or place I can go to read more discussion like this?
Thanks again, John On Tue, 2002-12-24 at 05:43, Brian Ewins wrote: > 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: ><mailto:[EMAIL PROTECTED]> > > For additional commands, e-mail: ><mailto:[EMAIL PROTECTED]> > > > > > > > -- > To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> > For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
