arc42 - Version 7

(for DE see below)

English Version

Finally, after extensive discussions with users and our committers we released a new version of arc42. Fully compatible with prior versions, preserving the established template structure, v7 has become even more pragmatic and compact. That makes using the new version simpler and more efficient than ever before. For v7 we vastly improved documentation and explanation of arc42 - creating two extensive sites (docs.arc42.org and faq.arc42.org). For a more detailed intro, see this post on the innoQ blog.

Deutsche Version:

Endlich, nach langer Diskussion mit Nutzern und Comittern haben wir eine neue Version von arc42 veröffentlicht. V7 ist vollständig kompatibel mit früheren Versionen. Wir haben die bewährte Struktur komplett erhalten, sämtliche Erklärungen und Hilfetexte jedoch gründlich überarbeitet und noch pragmatischer und einfacher gestaltet. Die Nutzung dieser neuen Version wird damit noch einfacher, als das bisher war. Insbesondere gibt es nun zwei umfangreiche Websites mit praktischer Hilfestellung ((docs.arc42.org and faq.arc42.org). Mehr Infos in diesem Post (im innoQ Blog).

FAQ for Software Architecture Documentation (with arc42)

I'm currently working hard on translating our German book (see this post) - which will be named "Communicating Software Architectures - lean, effective and painless documentation"). It's already on Leanpub, my favorite eBook publishing platform.

FREE in various formats

As arc42 is deeply rooted in open-source, I decided to extract the FAQ-section (frequently asked questions) from that book and make it available for free. As mentioned above - translation is not yet finished, and many of the questions in the FAQ collection have a "t.b.d" tag attached... but I'm quite positive I'll have the whole stuff translated until December 31st 2016.

Many categories of questions

I organized the (currently more than 100) questions in the following categories:

• A General questions
• B Questions on methodology
• C Questions on arc42 sections
• D Questions on modeling
• E Questions on arc42 and agile methods
• F Questions on tools for arc42
• G Questions on arc42 and versions / variants
• H Questions on arc42 and Traceability
• J Questions on managing documentation
• K Questions on customizing arc42

Your input is welcome

If you encounter questions around architecture documentation in general or arc42 in particular, let my know: DM me on our new @arc42Tipps Twitter account or email me on info-at arc42.de. By the way: I'm very grateful to innoQ for supporting arc42.

arc42 now has open source repositories

At Bitbucket you now find our arc42.org open source code repositories. They are independent of the arc42 architecture template (will someday maybe serve as examples for the latter).
I just comitted two small utilities for Pdf manipulation (PdfStamper and PdfUtil) - both are not "finished" but working...

Issue trackers are live and actively monitored.

The third project, DupeDetect, handles duplicate entries in your geocaching logs… In case you don't know what that is, don't mind. Geocachers *will* know. Hopefully we make this available as a cloud-based service soon, parallel to the source code.
(did I ever mention that I absolutely *love* the Atlassian guys…)

Großartiges Beispiel für Architektur und ihre Dokumentation

Stefan Zörner hat seine Open-Source Schach-Engine DokChess bei Sourceforge veröffentlicht und die aus meiner Sicht beste Architekturdokumentation aller OpenSource Projekte überhaupt geschaffen - Chapeau! Er verwendet dazu übrigens arc42 - freiwillig!










(lang andauernder Beifall meinerseits…)


Und wo ich schon beim Lob bin: Sein Buch (in dem er unter anderem das coole DokChess-Beispiel erklärt) durfte ich schon vorab lesen und möchte es jedem Software-Architekten empfehlen!

Preisausschreiben (von der JAX 2011)

Auf der JAX 2011 habe ich folgendes "Preisausschreiben" ausgelobt:

• Sie senden mir (an info@arc42.de) in 3-5 Sätzen Ihre Erfahrungen mit arc42



• Bedingung: Wir dürfen diese Sätze (ganz oder teilweise) auf arc42.de zitieren.



• Die ersten 10 20 Einsender erhalten einen coolen arc42-USB-Stick :-)

also - positive wie negative Kritik willkommen... danke für's mitmachen!

ANTLR plugin on IntelliJ abandoned

too bad - one more plugin that doesn't work properly with my beloved IntelliJ: ANTLR works grammar development.

I inquired with Terence Parr, the definitive source for all ANTLR infos - and he admitted that the ANTLR plugin for IntelliJ has been abandoned, as it was "too difficult to get it to run properly".

Rescue is on its way - ANTLRv3IDE for Eclipse (3.5 onwards). Great plugin, great docu.

I stopped using Eclipse...

Ever had hassle with your numerous Eclipse plugins? With update-manager complaining about missing dependencies, which nobody ever could resolve?

With re-installing your (free) development environment every now and then?

After giving the latest Eclipse ("Galileo") a try, I just dumped it: After configuring Spring, Scala, webservice, subversion and a few other plugins, the whole app did not even bother to start...

Having been Eclipse user for several years, I am really grateful for their contribution to (Java) software development. But it has become an overly complex monster in my (humble) opinion.

I lighthearted moved over to IntelliJ-IDEA - their slogan "develop with pleasure" became true within the first hour of using IDEA (I tried both 8.1.3 and their early-access version 9). Grails and Groovy support is excellent, Scala plugin working fine, subversion support the best I ever had, even Clojure working (ok - that one can definitely be improved, but true lisp programmers should stick to Emacs)

Proud user of

Linus Thorvalds on GIT

It's already beyond hype: GIT, distributed version control system.

Linus talks (at Google) about his source-code-management history,
his aversion (hatred...) of CVS and subversion,
on distribution and other interesting stuff.

Not too good for subversion-lovers :-)

The Ultimate Authentication Device - but currently without market

That's what I was looking for the last years: A tiny, sleek, affordable, secure and really cool device for authentication: Forget about this plethora of different passwords and login-names. Just press the green-glowing button of the Yubikey - an imho revolutionary device invented and produced by Swedish company Yubico: It plugs into any USB port and behaves like a regular USB-keyboard. With the exception that it has only one single (mystically illuminated) key - and emitts a highly secure one-time-password every time this key is pressed.

Good to know: Their sdk (development kit) is open source, their business model is selling the hardware (starting from 35 US$ for a single USB-key, going down to approx 10 US$ for larger quantities).

I could really solve all login and authentication problems - would there be enough acceptance around the great players. Steve Gibson had a great coverage in his security-now podcast - but my favorite sites still don't use neither OpenID nor YubiKey...

But hey - wait: Most revolutions took a few month to really take off...

major update on arc42-site...

(english version below)

Für alle arc42-Anhänger: Gerade haben wir die neue Version der Website live geschaltet -
grundlegend überarbeitet, mit der brandaktuellen Version 3.2 des bekannten Architektur-Templates an Bord.

Ausser dem neuen Layout gibt's auch viel neuen Inhalt, jede Menge neue Downloads und eine ausführliche Dokumentation des Templates ("How-To...").

---

English version:

Just in case you're interested in our arc42-site (free resources for software architects) - we just published a *major* update, including the brand-new version 3.2 of the template, an improved download-section and a (cool!) documentation of the template ("how-to").

Feedback welcome!

Highly regarded Rickard Öberg creates "New Energy for Java"...

Only a few people combine creativity and the ability to deliver solutions... one of them is Rickard Öberg. His brain- and codechildren range from XDoclet to the JBoss application server, cool stuff.

Now he's back with the idea (and framework) he calls new energy for java in a lengthy blog entry.

He names it "QI4J" (pronounced "chee for jay") - a framework in the area of domain-driven development (I blogged about it here). Well, just in case you're architecting software systems, you should check it out...

Three links you for GPG ("gnu-ish PGP) on Mac

Just in case you need to setup a PGP-like infrastructure on Mac-OS: I recommend the GNU-GPG-tools
for it - and found helpful instructions on MacGPG-site.

1. Download the files from Sourceforge. You'll surely need "GnuPG for OSX" and "GPG KeyChain Access" (makes life much easier).


2. Point your browser to the cool docu (by Zeitform).


3. In case you need to pgp-encrypt EMail (I'm sure you need to!), get GPGMail (from SENTE), also free.

Installation is very straightforward.

Then you

• (must) generate your own key (unless you already have one and it's still valid!),


• (should propably) upload your public key to a keyserver (the default keyserver of GPG works fine),


• (have to) find the keys of your communication partners, either on the public keyservers or from them directly,


• (should) publish your key's fingerprint, so others can verify a downloaded key... (put it on your website, find mine here). In case your're too lazy to klick: 9E64 477B 0BCF A2C6 C868 68B3 CF32 9C31 4E1A 26BA

And you're done: From now on, your mails or files can look like (snippet from the pgp'd version of this post:)

-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.7 (Darwin)

hQQOAwi7HCcW8Lx9EA//RSsewJBuWJf+oYvddQvghwtU2gGkHT5IRv7xWdUTC9LY
YEnGj3CdVroLUwnJDor7ehgFGCCEnx64mmTTcwjrMU2BOKdBlc3ZN7xL02LQEMl/
JjUIuvZqEWvSpzxMt3Arcb8kL3E3jU3fIh+vD93ZegwRMkhJzeS1hss0JHyc3lEq
EJWNdB0LLZ6+tHmL5hebvycDIdPftBcM0+jGZtz9+nD8gVFRFiIDyJ8IJy0nYl+h
iQyFivB4E5LEwq4mZrpooxqaqlbRexEjc+k8jwQrhGc54F6y609BWbX518jGDKIr
dc7KP75J8p8nY1+EokOW3IH4eSYYLww7yxN85/A+X4cEQMrI7yDcVS/ex9B/eK0L
tVAmlHvYsuRE583G/vxwsSbSoHOORux5MmgaEM7U50WH8urNh47ej0ztE0VQWP3C
A7U8JbyCmQbWzHanK64RcF++BxUulyE2u85Cuiz+yjZHuv9kri84gG6pubG9d6H/
ZSnyFtt1uvzR6tGWRG8LQit66dnZfQSxXH/OED0epPG9HuNVynlkL0WEtE7wnnFd
7BDebS/IGk6De6Y7i2alJpCHwILgEGVHpeGLrLQc45Jux7NmfEyrYGRS6JZyEFPM
r5eeBb0lPxUzFJlIaCwZDk2AS6dA5pGMPR5t9NArVgUWoe7autNgOyQ0VRn0HzAP
/14eWlTynKsVkyCyXkf8nCNAPxCZrTkNo7h8rc4pEcbtIDk6wIkxUMnW+QlLHDPd
8Jte2rJVorcGEP7niz/QSKZ5aoV4HI1kZcJrOuvm2zEoCuAmE+ThU174VlVHm/KW
hOq2k9TzS4QPwfMqQVD3wCL+w0tIf3kVI6PhTjBfi35rFbn8ambRobvDyS9mlvXN
+EZl4f4zW9+UNwYyVHdsLG1trZ5cOw7Gaoys6mkg+hCPLIYtFU456dy63ZPKY9Kp
QddlqW8bWwv76irP9Kh9tbbfX2CoVeUl+5NoU5Eij1cECI43EW+syWdoPQMoydch
Rw7IYyrRmyMALZF76JpzYlZrVKry+W/4Z/0KaD+JbYH1j5LefRC10XEI2n9utr04
2iNvrrBvYgEVGbbdXYhSUmxTkvGq3njC55PHura3gxI2NVa74qt1y3tGcO9vvIgA
npblWP0r1elJBC7VyzUjaf10H0C0RAEBBekmdTZs3bXkbtZTPxoZpSi6skFRBrzh
8eezu....

Dynamic Language Shootout...

You want a new notebook? You know Ruby, Smalltalk, Scheme, Lisp or Python (or Prolog...)?

There's a dynamic language shootout (in German) with some nice prices (a notebook, an iPod etc).

You gotta release your solution under GPL... and fill in a form, seems pretty harmless. And: The task
is brilliant, a little AI, a little UI, loads of fun.

Go, participate. If I find the time, I'll submit a Prolog solution :-)

Heard of JBoss-Seam? Want to know what it's all about?

Manning has posted a (free) well-written chapter of a forthcoming book on Seam on their site...

I wonder wether critique and suggestions will be incorporated into the final version... maybe somebody from the JBoss-Seam-Team should try...

Drools-Puzzle #2: And the Winner is...

Scott Reed (.... applause ...)

Dunnit! A dozen solutions to the second installment of the (now famous!) Drools puzzle contest arrived at my desk, originating from brave men spread all over the world (all right, at least from Australia, South-America, North-America and Europe).

I evaluated during a brief holiday in souther Turkey - without internet access and with only Drools 4.0.1 plus Eclipse 3.2 installed on my MacBook. That initially sounded all right for me - but wasn't. Read on why I failed to evaluate a few (gorgeously interesting) solutions with this setup!

C++ for highest performance

Like in puzzle #1, all rule-based solutions were outperformed by Dirk Farin's C++ version. Dirk: You're great. But we're using rules to factor business-logic out of java applications... If we ever need to build something ultra-performant, we'll surely remember your approx-one-nanosecond-solution. Btw: I took your source and could immediately build-and-run it on the Mac :-) Dirk used numbers instead of (symbolic) names, which makes his solution-output a little hard to read...

Although admirable in performance, Dirks' solution still is a C++ program... and I didn't let those count in the puzzle...

Standalone CLIPS

The next hurdle in evaluation came from Johan Lindberg from Sweden: He send a pure CLIPS solution, which wouldn't run in Drools either...

Johan seemed to be pleased with the puzzle and asked for more. Johan & Dirk - please send us Drools solutions next time :-)

Only Seeing is Believing

Like in any athletic competition I required the winning solution to run on my machine - during my evaluation. I didn't actually feel the urge to debug or modify submissions so they would/could run in my limited setup (see above). Although this may sound unfair ("but we're still using 3.x in our project"), I had no other chance.

Therefore, solutions without source-code (Carlos Bustamante), with requirements to "mvn install" additional drools modules (Geoffrey DeSmet) or with Drools 3.1 rule syntax didn't count either. Sorry guys - life can be tough. More on Geoffreys' solution later on...

Now there were 7 solutions from 6 participants left over to compare. It had already gotten hot in
the mediterranean hemisphere - I noticed other people jump into the pool, I smelled roasted garlic and delicious turkish mokka. But I kept evaluating...

Simple and Complex Rules

No participant bothered with any explanation, how or why his solutions works. They all did work correctly, by the way. But with several of them I still don't know why. The golden ideas of their creators, those shiny bits
of knowledge - buried in crusts of unexplained code. I hear people talking about self-explaining code, of the truth that only lies on code, never in documentation. Might hold for guru-readers, but not for humble-ones like myself. I need explanation, abstracted away from source-code. Even for our simple puzzle, several solutions spanned more than 100 lines of code - mostly without any docu.

For me, this is one lessons I (once again!) learned from this puzzle: Care for understandability.

All solutions gave correct results - but I evaluated only one (from John Kirchmeier) as "clean-and-simple", without fancy decoration, and gave it top-score in "Drools code understandability". Well done, John!

One case in particular gave me headaches. One participant (he'll know who I'm talking about), a real Drools-guru, supplied a solution based on the DroolsSolver approach (formerly known as Taseree). In my remote holiday location, without internet access, I couldn't even build it. He was the only one to submit a solution based on a scoring approach - his program creates just one (arbitrary) family, scores it and, if the score is not perfect, modifies the family... The result surely works - but at what price? The "business logic" of our simple riddle gets mixed up in six business rules, one scoring rule and a pretty complex (java) function to re-order the family relationships - naturally based on Generics, a FamilyMoveFactory and two Switcher-classes... Impressive stuff, I'm sure this approach will solve generations of extremely complex riddles - but simply overwhelmed me. Impressiveness doesn't count.

Another sting to another participant: 18 rules for this puzzle might be a little over-modularized...

Running for Gold

Now that I bashed a little on overly complex solution approaches (yep - rules can be kept simple yet correct!), what solutions remained in the race for the title? (Running on a MacBook Pro, Intel Dual-Core, OS-X 10.4.10, 2GB Ram, Eclipse 3.2 with Java 1.5, running exclusively Eclipse and Finder, using System.currentTimeMillis() for timing). I ran every solution 3 times and took the lowest values for the overall performance (that is: initialization plus rule-evaluation!).

1. Scott Reed, 1596 overall, 37 for Drools


2. Christiano Guiffrida, 1682 overall, 33ms for Drools


3. Dan Berindei (first solution based on fact-retraction), 1720ms overall, 110 for Drools


4. John Kirchmeier, 1760 overall, 53 for Drools


5. Dan Berindei (second solution, without retract), 1812 overall, 65 for Drools


6. Chris Barham, 1875ms overall solution time, 56ms for Drools.


7. Reginaldo Delfino, 1956 overall, 77 for Drools

Scott - congratulations. Your solution outperformed the other Drools solutions. Please supply the next puzzle to the Drools community!

It was close: Christiano's and Dan's solutions were pretty fast too. My personal evaluation
on understandability: The fastest solutions score 4 out of 5 possible points.

With 1760 msec overall runtime, John Kirchmeier's clean-and-elegant solution provided an
excellent compromise between efficiency, maintainability and understandability. John: You're my moral winner, with a rule-understandablity-score of 5.

Download of submissions

I do not provide downloads for the submissions - maybe the participants can put their solutions
in the JBoss-Wiki and send me the link - I'll post those here!

Hints for the Future

As code quality remains to be very subjective, it cannot easily be evaluated by a single referee
in our little contest. Taking pure performance clearly identifies a winner - but as a software-architect
I'd definitely pick the solution with the lowest overall complexity and acceptable performance.

I propose that from now on each "puzzle-creator/judge" publishes her or his set of evaluation
criteria... (I failed in this respect - sorry!). Next time I'd even propose a naming convention plus a predefined "main" class structure:

   main(...)
   //...
   long start = System.currentTimeMillis();
   init_rule_file();
   long begin_fact = System.currentTimeMillis();
   pre_init_working_memory();
   wm.fireAllRules()
   long end = System.currentTimeMillis();
   //...

Thanx again for participating!

Maaaany bugs fixed in Drools...

The Drools-team just published their maintenance release 4.0.1 with loads of bugfixes (described here).

Thanx for your good support, guys :-)

Rules-Programming-Contest, Round 2

Round 2 of the JBoss-Drools puzzle contest just started...
(this time it was *me* who had to post the puzzle...)

Deadline for submissions is September 14th, 2007.
You can send your solutions to droolspuzzle@gmail.com

=====================================

• Three men, Abel, Locker and Snyder are married to Edith, Doris and Luisa, but not necessarily in this order.


• Each couple has one son.


• The sons are called Albert, Henry and Victor.


• Snyder is nor married to Luisa, neither is he Henry's father.


• Edit is not married to Locker and not Albert's mother.


• If Alberts father is either Locker or Snyder, then Luisa is Victor's mother.


• If Luisa is married to Locker, then Doris is not Albert's mother.

Who is married to whom and what are their sons called?

Taken from the German book "Denken als Spiel" by Willy Hochkeppel, 1973 (Thinking as a Game).
=====================================

The Rules of the Contest

More info on the contest.

We're looking forward to your contributions -
let the rules rule...

Finally: Lisp-plugin for Eclipse

We had to wait awfully long for a Eclipse-Lisp plugin (named Dandelion) to appear...

Version 1.0.5 even comes with support for Eclipse 3.3 (Europa) and with SBCL bundled (at least for MacOS and Linux).

I'm sure to blog some experiences one day (when my current customer projects will give me some time...)

Pragmatic Re-Re-Branding

A good move: The (awesome) rule-engine "Drools" is back- including a new version of its logo:



Mark Proctor writes in his blog:

"Having received community feedback 4.0 will start the push to reclaiming the Drools name.... So to help speed up this process, I would please encourage everyone now to use "JBoss Drools" in any articles, blogs, talks etc."

I'll start: JBoss-Rules will be called "JBoss-Drools" from now on (again)...