Typically, I work in Java. When I’m not working Java, I’m working Perl. Sometimes I even do work in Prolog (no, really!). But once in a while I venture into the C++ world.
I’m not a fan. Having my classes split across multiple files. Having the parent class decide what I can and can’t subclass. Trying to decide whether the caller or callee has responsibility for deleting an object. That said, there is a Perl-ish “Theres More Than One Way To Do It” (TMTOWTDI) thats kind of nice.
But with all the complexity inherent in a C++ program, documentation is all the more important. A work mate put me on to doxygen. It can be summarised as Javadoc for C/C++. Technically, its more than that – it can handle a range of languages and input files (even Java!), but the largest use appears to be the C/C++ arena.
Just like Javadoc, you create special comments throughout your source code, which get turned into documentation. And, you can insert special directives in these comments which have special meanings. Some favourite examples are:
- @todo to flag a To Do item – your documentation will include a TO DO page summarising all these items
- @version to detail what is in a particular version
- @bug to flag a bug. Again, your documentation will include a bug page summarising all flagged bugs
In some ways, Doxygen is more powerful than Javadoc, out of the box. It can generate HTML and LATEX formats (Javadoc can do LATEX, but you need a custom doclet). The default pages show the class hierarchy, as well as providing links to the source code, neatly colourised and formatted. And most impressively, it can integrate with DOT from GraphViz to do graphical representations of the class hierarchy, as well as simple “has-a, is-a” type diagrams.
The flexibility comes at a cost – typically you have a big config file to tell Doxygen how to run (It reminds me of the “less is more” nature of Java versus C++ – Java may have less language features, but is more straightforward to debug and use as a result). And the nature of C++ in particular, with a class definition spread over multiple files can make some of the documentation decisions tricky: Do I put the method summary and method detail in the header file, or the cpp file? Or one in each? Whichever I pick, I always end up swearing once a coding session and having to flip around source files to find the info I need.
Niggles aside, this all makes C++ programming a lot more manageable. On larger projects, I can hand over the source to another developer and know they have reasonable documentation from the start. And on smaller projects, I can keep track of the issues, and architecture more easily. If only my IDE supported it, like Eclipse supports Javadoc…. 