I’ve used doxygen in the past to provide hyper linked API level documentation for C++ source code, but until now didn’t realize how useful the diagrams it can produce are. With just a few configuration file alterations it can produce a graphical hierarchy of classes, a class graph for each documented class, a collaboration diagram for each class, include dependency graphs and call graphs for functions. All this is hyper linked and integrated in with the API documentation produced. Wonderful stuff! Check out an excerpt from the graphical hierarchy of classes created for a project I worked on this month:
Though UML and other graphical modeling approaches have been derided, I find a UmlAsSketch approach very useful in managing complexity. The problem is managing this complexity and handling change as a program is continually developed. It is a shame to have to spend precious hours drawing UML diagrams to document a software project, but then its also extremely useful to have access to such diagrams to figure out the design of a system. This need can arise if you’re new to a code base or you’re coming back to some code after a long while. It can even happen when being overly involved in the gory details of software development and losing sight of the overall architecture.
Being able to automatically generate graphs and diagrams from an existing codebase is extremely useful in quickly understanding (or remembering) how a complex set of code is structured internally. It saves you from manually drawing the diagrams and notes used as bread crumbs to mark progress through the deep dark woods of a complex code base. doxygen is a great GPL’d tool for achieving this for C++ code (and other languages). Give it a go!