- 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.
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.