Drinking your way to drydock

One of today's areas of focus for me at work is in producing some useful training materials on embedded documentation for software and best practices for java development in our world of concurrency and multi-core systems. The guy that is tying these two disparate ideas together for me this Monday is the esteemed Brian Goetz.

Goetz is a master of caffeinated concurrency, well known in Java circles (as I've written here before, please grab Java Concurrency in Practice at once if you haven't and also catch his InfoQ presentations). Please check out 'Are All Stateful Web Apps Broken?' if you work with Java Web Applications - turns out most of us are deploying these things half blind with our fingers crossed and praying that the gods of concurrency will be kind to us. There is a better way.

It turns out that Mr. Goetz also has a great (though somewhat dated) write-up on best practices of software embedded documentation for java. It was written in 2002 and the JavaDoc tool has been updated a bit since then (for instance, "package-info.java" didn't exist yet for package-scoped documentation and you had to include a package.html file mixed in with your java). Still, bar-none the best single article I've read on the subject.

I hope you know this will go down on your permanent record

Things other than work (or maybe instead of work) that I am paying attention to today (technology version):

• Gregor's Cloud Talk
• ThoughtWorks Panel Discussion with Fowler and Co.
  
• String Template
  
• I'm re-reading Andy Hunt's Pragmatic Thinking & Learning - if you haven't read it, please do.
  

Well, back to work. Trying to come up with a way in which to best get across to folks some useful (and to contrast it, some very not-so-useful) ways in which embedded software documentation (in our case, JavaDoc) can be applied. Mainly, that it not simply repeat what the code should already tell you (and if the code is not telling you, chances are that the comments applied to it are smells pointing to a refactoring opportunity). Code should not be commented, in general. Methods can be commented occasionally, but should be scrutinized to ensure the comment doesn't stink (ensure that it's telling you something valuable that is not possible to express in the method code). Classes, packages and modules are the things needing the comments: you want good example usages. You also want doc on policies that can't be expressed in code (thread safety, for instance), though annotations can be helpful in this case (Brian Goetz has some recommended concurrency annotations in his seminal Java Concurrency in Practice book.

JavaDoc at the package and module level via a package-info.java class can be extremely helpful and is too rarely done. I can go generate Javadoc for a module of code and even if there is no explicit JavaDoc markup made for the individual classes and methods, it provides me a lot of valuable information out of the box; however, it tells me nothing about the purpose of the package or module as a whole. That's what's missing and what often requires the creation of some external document that very quickly gets (and stays) out of sync with the code.

I'm trying to put together some simple examples that get this point across. Keeping this point across time and a large organization is the challenge. Those that will instinctively 'get' this already do, so I don't worry about them; it's weeding out those that never will - since I'm not King and can't fire them on the spot - to get to those that just need a little bit of encouragement, some breathing room and a new perspective. This problem isn't specific to this topic - it's teaching and adoption and empowering everyone to own our software, to own their own career and to know that you're not just a drone in Sector 7G waiting for the whistle to blow so you can slide down the dinosaur.