Sometimes it is useful in my work to modify someone else open-source code or find out how to develop specific things for your own application. However, not all software have good documentation.
What is a good way to understand the overall structure of a code base?
For example, which routines calls which routines, etc. I might use a documentation tool such as Doxygen for this purpose myself, however, I was wondering if there is a better strategy?
The following threads are tangentially related:
For the first part of my thesis, I spent 18 months modifying undocumented Fortran code, and one of the first tasks was to try and understand the overall structure of a code base. The most important thing I suggest you do is take notes in a text file any time you figure something out. You don't want to have to relearn or rediscover things during this time-consuming and frustrating process.
In my case, there was no "API" to speak of, in that the arguments of functions weren't self-documenting, because the previous programmer used Fortran 77-like style, and thus, short identifiers with little to no hint of what they meant. There were no tests, and since it's Fortran, no headers. Adding even more fun to the mix, there were a couple functions here and there written in C or C++.
Things that worked for me (assuming you work in Linux):
grep. Learn to love grep; you'll use it in the shell to find where functions are declared and called, and the output will tell you what files to look in.nm. It can be useful on libraries if you don't have source code for them, but want to know if a function you encountered is in that library. However, it only works if the library's symbols haven't been stripped.print statements. ddd and gdb are great, and on virtually every Linux system out there. Feel free to use your favorite debugger.Things I'd wish I'd thought of earlier, or just weren't options for me:
gcov and lcov to do a coverage analysis on typical runs of the code, if you have examples or executables to work with. If there are examples that are supposed to execute large parts of the code base, these two tools combined will tell you how many times each line of code is visited. It's most useful with debugging flags enabled. If a part of the code isn't visited at all, it's probably less important to understand it right away. If a part of the code is visited a lot, it's probably worth understanding what it is. Maybe the code is executed a lot because it's an unimportant loop, or it could be a key function that a lot of other functions rely on. You can't tell just on the coverage analysis, but the coverage analysis gives you some idea of where to focus your time.splint can tell you if something fishy is going on in the code, like some variables are never used.dot and graphviz to generate call graphs and see how many times functions are called, like the coverage analysis. For complex codes, a graphical analysis could be a lot more helpful.
I always tell my students to read a code from the bottom up: you start in main() and see what it calls. Typically this is only a small number of functions. Then you look into the functions called from main() which typically define the overall flow of the algorithm (time stepping loop, assembly, solver, output, etc). Go two or so levels deep to get an overview of the algorithm from 30,000 ft. The rest can often be gleaned from doxygen documentation etc.
But as I said, the message is: Read code from the bottom up.
