Code documentation

Nope, I did better. My simulator has got some documentation.

I'm not a big fan of lengthy and hefty technical documents. When I worked as application developer, I came across those 100-and-more page documents that explained in writing what a single function or method was supposed to do, the way was supposed to work and how it fitted in the overall project structure. After a couple of months, those documents used to become outdated, unreliable and misleading. Basically, they were a waste of money and time for anybody - I'd rather go for no documentations than a misleading document.

But hey, that doesn't mean documentation is all bad. What if I had very light documentation, describing what the inputs and outputs are, fully embedded in the code, easy to generate and update? That is, some sort of way to auto-documenting the code I write.

I must be stating the obvious, but that's exactly what Javadoc does, with some limitations. Javadoc homepage on the Oracle site fully describes Javadoc main features, functionality and limitation, so I won't go much into details. 

I focused my documentation on the interfaces, interface methods and classes definition. Javadoc documentation is generated within the IDE, which provides tools and resources to write documentation quickly. I rarely document how my Java methods work - I often keep code implementations easy to read by using good formatting templates and one-shot variables, since I believe good code snippets document themselves. Eclipse helps keep documentation up-to-date by changing Javadoc comments during code refactoring, avoiding outdated documentation.

For high level documentation, I use UML2 tool for Eclipse. UML2 generates maps of class and interface dependencies, giving me an overview of the overarching project and helping me spot wrong dependencies (dependencies that don't follow the IoC model) or opportunities for optimisation.