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.