This blog is starting to look like an advertisment for Atlassian, but I just have to tell you about some stuff I wrote over the weekend (with some help with the finishing touches from Aslak and Carlos, the latter being in town all the way from Brazil).

You know when you are trying to write that long anticipated documentation for your latest open-source library and you want to include some code samples in your tutorials? Only problem is, the project is coming close to a release but you're still refactoring like crazy. So how do you keep all those code-snippets up-to-date?

Confluence to the rescue! Your open-source library is the latest and coolest cutting-edge stuff you can think of so of course you are using the latest and coolest cutting-edge tool to write the documentation in. For those who don't know about it: Confluence is basically a wiki with some really nice features like for example an awesome look-and-feel that makes me all warm and fuzzy inside.

So, one of the features in Confluence is that you can easily extend it with new macros. This is actually a result of that they are basing their wiki rendering on Radeox the same rendering engine used by SnipSnap.

So I basically just wrote a macro that extracts code snippets from any url (hint, think viewcvs) and renders them into a Confluence page.

You basically puts this into your code (easily done with an IntelliJ surround live template):

// START SNIPPET: boy
public class Boy {
    public void kiss(Object kisser) {
        System.out.println("I was kissed by " + kisser);
    }
}
// END SNIPPET: boy

Then you add the following to your wiki page (I've snipped the long viewcvs url that points to my java code in cvs, because it wrecks the formatting of this page completely):

{snippet:lang=java|id=boy|url=[long viewcvs url deliberately left out]}

Don't get fooled by the "lang=java" thing, the only thing that does is to render the content as a code block with java syntax highlighting. This actually works for any language, xml, text, html, whatever. Thanks to Martin Fowler who explained the idea of putting the snippet demarcators into the code, which avoids any crazy ideas of having to parse the Java code and makes the same thing work for virtually any text file. Simple, elegant and powerful, almost Wardish.

Have a look at the following page, there is not one single line of java code in that page (except for that snippet that for some reason doesn't work properly, I'll look into that later):
http://docs.codehaus.org/display/PICO/Two+minute+tutorial

By the way, I haven't tested this but the macro probably works just as well in SnipSnap or any other Radeox based applications. It does not depend on any features in Confluence whatsoever.

The code temporarily lives in the NanoContainer CVS:
http://cvs.codehaus.org/viewcvs.cgi/snippet/?root=nanocontainer

So, one year huh? It's been great fun and we've accomplished a lot. Projects like AspectWerkz, Drools, Groovy, PicoContainer, JMock, QDox, XDoclet 2, Nanning, Plexus, XStream shows that Codehaus in a short time has attracted a lot of innovative projects. One reason is probably all the great and fun Hausmates and another reason is probably the amazing infrastructure. People that get sick of Sourceforge's low quality service has all the reason in the world to move. We have to thank Bob The Uberdespot for that, but I should also mention Atlassian whom never thinks twice about giving away an open-source license or two of their excellent products. I wish more companies worked like that (and there is, but I just wish *everone* worked like that :-) ).

A birthday is a time for review. What can we be better at? I think something we have to start thinking more about is how we face our users. Codehaus used to be alot about technology but there has been a movement lately to try and clean up our public face. We should definitely think more about our documentation.

That said: Hipp, hipp, hooray!

Wow! I've been looking forward to this for a long time. Subversion 1.0 is finally released. It's been stable for quite some time now, but having a 1.0 out means we can probably start moving some of our projects over. For example we've been discussion moving PicoContainer to Subversion after the 1.0 release of Pico which is due soon. Dealing with some of the idiosyncrasies of CVS is finally starting to wear me down. CVS is still a lot better than many other version control systems but things like moving files, renaming stuff, absurdly slow tagging and so on is getting tiresome.

http://subversion.tigris.org/

Weee! The JetBrains Resharper EAP is open! This could be the turn-around for .NET development!

http://www.jetbrains.net/resharper

I can't wait to give it a whirl! They seem to have kept all the key bindings exactly like in IDEA. The joy!

Keeping things simple is not just about keeping a design simple, it can also be applied on micro-level.

For example, today me and my pair-mate refactored some especially nasty and complicated code where this really made sense. Basically it was a thing which hooked up events to the various nodes of an hierarchical structure and maintained those event-listeners when the hierarchical structure changed. The old code used some quite complicated logic to unhook event-handlers when a branch got removed and to hook it up when a branch got added. The refactored implementation basically just unhooked all events from the old nodes and hooked everything up again to the new nodes whenever something changed, regardless of what changed. This made the new implementation do things a little bit too much, but the the code just looked so much cleaner and maintainable. (Which in my experience means less bugs.)

So in essence, by choosing the much simpler implementation strategy we could produce code that was much better.

The good thing about this specific code was that it was exceptionally well-tested with small well-readable test-methods. So we basically ripped out the old nasty code and started to reimplement the refactored solution by fixing the tests one-by-one. It was truly a pleasure! People that say TDD is boring (nudge, nudge Chiara) should really try to learn it properly before making such judgements. Btw, this also teaches you that it's much more important to write good tests than to write good code.

Cool, Prevayler is finalist in the Jolt Awards: http://www.sdmagazine.com/pressroom/jolt_finalists_2004.pdf.

Boy, I've been using Prevayler for around two years now and it's certainly a very powerful alternative to the relational-mapping dance. Of course, the toughest competitor in the category is Hibernate. ;-)