Doxygen niggles

I’ve been using Doxygen recently. It can scan a body of code and produce reams of linked documentation and diagrams. I, personally, don’t really use it for its documentation, just for its diagramming. I’ve always believed that if I can’t draw a neat and tidy picture of the relationships between pieces of code then the design needs fixing.

I used to drop in and out of drawing my own cut down version of UML diagrams as I designed code. When things got complicated I’d draw a diagram and when the diagram was hard to draw due to the twisted nature of the code I’d adjust the diagram until it was “nice” and then apply the same transformations to the code. It usually seemed to result in a better design. Now I try and let my tests drive my design and this diagramming phase seems to have lessened in importance.

My hand drawn UML-like diagrams weren’t usually kept; often other people on the team didn’t know my version of UML (or even the real thing) well enough to get much out of the simple diagrams so there wasn’t much point in keeping them. More importantly they broke the DRY principle - the diagrams were derived from the code but maintained separately. As soon as the ink dried they were likely to be out of date and out of sync with the code.

The fact that Doxygen automatically generates the diagrams from the code removes the DRY issue; add a Doxygen build step to your build and the diagrams are always up to date. That they can either be in ‘UML’ or a cut down format and that the format is down to how the tool generates them and not some personal choice removes a lot of the ‘discussion’ about how best to represent the code in pictures. That they’re embedded in ‘documentation’ and clickable and the clicks let you navigate to the documentation or the source means that they’re much more use than hand drawn diagrams.

I’m not one for masses of comments in code, and I abhor those block comments that explain ever parameter in long winded text that tries so hard to add value over that given by appropriate naming, but… Once you’re using Doxygen for diagrams you may find that adding a few comments that indicate intent rather than process can make the generated documentation more useful.

My problem with Doxygen is that its parser isn’t quite as clever as it could be. I use namespaces a lot. I find them useful. I always use the fully qualified namespace name in header files; I have a rule about not using using directives in headers. In cpp files though, I usually have a bunch of using directives at the top to make the code less cluttered. I’m not sure if it’s good, but it works for me.