Susheel’s Blog

When it comes to documenting code, there is nothing better than a documentation generator, and when you talk about document generators, none is perhaps more widely adopted than Doxygen. I am using Doxygen in my current project and I have been using it in on the last 3 projects. Doxygen is pretty good when it comes to generating documentation and I must add, does the job pretty well too. But besides it’s conventional use, I decided to try and experiment with it a little bit more for this project. I have always believed that unnecessary and excessive documentation is counterproductive to a project life-cycle. Mindlessly making Word documents and adding it to a folder often has no value addition what-so-ever to a project. This is simply because this documentation never gets properly referenced by the developer, designer or the team-leader especially during the time of intense project pressures.

Before you brand me as a development process heretic, or deem me as a free willed do-what-you-like vagabond, let me make things clear. I am neither of those. I am very much in favor of proper and detailed documentation and I myself follow strict processes (, too much sometimes,) in every cycle of the development process. Regarding documentation, the thing I find inconvenient is that fact that, documentation gets fragmented into different files and often into different locations. Some teams are careful never to let this happen and often do control this by using very specialized software (Rational products do ofter such software). But products like these can leave a hole in the pocket of large corporations, and for budget teams like ours this is simply not a viable solution.

From the very beginning I had this gut feeling that documentation should be at one single place and accessible via one single interface. I will go a step further and say that I, as a developer, would like to see design plus the documentation plus the code at a single place at any given time. This is immensely helpful when you are into heavy development. You can link back to the design at a click of a button and if you are intuitive enough to use the right tool, quite literally link to the exact spot you want to go. This to-and-fro movement from documentation to design to code and vice versa can serve as a powerful counter check mechanism. So the docs, the code and the design have to be in perfect sync for it to work. When one changes, everything needs to be updated. I found this very helpful in managing the current project. Kept me and the team always focused on macro and micro level design from the very beginning.

We started off with this idea in our project and decided to implement it via Doxygen. Since Doxygen builds docs in HTML, extending it to incorporate such functionality was, well, trivial. Believe it! I haven’t spent more than about 1 day (total) on this stuff. We have made no code changes to Doxygen program. All our changes are superficial needing only to use already built-in functionality of Doxygen and some minor (but intuitive) HTML tweaks. During this release we went a bit further and decided to link our bug-base to the design-documentation-code nexus. It has proved to be even better than expected. Not all things have been ironed out yet, infact a lot remain, but it already seems like a nice way to handle things.

Design documentation

Class Documentation

Class Diagrams

I am not at a liberty to show more diagrams for the design but rest assured they are there.