Reading/Understanding third-party code

Question

When you get a third-party library (c, c++), open-source (LGPL say), that does not have good documentation, what is the best way to go about understanding it to be able to integrate into your application?

The library usually has some example programs and I end up walking through the code using gdb. Any other suggestions/best-practicies?

For an example, I just picked one from sourceforge.net, but it's just a broad engineering/programming question: http://sourceforge.net/projects/aftp/

Answer 1

One of the better ways to understand it is to attempt to document it yourself. By going and trying to document it yourself, it forces you to really dive in and test and test and test and make sure you know what each statement is doing at what times. Then you can really start to understand what the previous developer may have been thinking (or not thinking for that matter).

Answer 2

Familiarize yourself with the information available in the headers. The functions you call will be declared there. Then try to identify the valid arguments and pre-/post-conditions of the functions, as those are your primary guidance (even if they are not documented!). The example programs are your next bet.

Answer 3

If you have code completion/intellisense I like opening up the library and going '.' or 'namespace::' and seeing what comes up. I always find it helpful, you can navigate through the objects/namespaces and see what functionality they have. This is of course assuming its an OOP library with relatively good naming of functions/objects.

Answer 4

I frequently use a couple of tools to help me with this:

• GNU Global. It generates cross-referencing databases and can produce hyperlinked HTML from source code. Clicking function calls will take you to their definitions, and you can see lists of all references to a function. Only works for C and perhaps C++.
• Doxygen. It generates documentation from Javadoc-style comments. If you tell it to generate documentation for undocumented methods, it will give you nice summaries. It can also produce hyperlinked source code listings (and can link into the listings provided by htags).

These two tools, along with just reading code in Emacs and doing some searches with recursive grep, are how I do most of my source reverse-engineering.

Answer 5

Great question. I think that this should be addressed thoroughly, so I'm going to try to make my answer as thorough as possible.

One thing that I do when approaching large projects that I've either inherited or contributing to is automatically generate their sources, UML diagrams, and anything that can ease the various amounts of A.D.D. encountered when learning a new project:)

I believe someone here already mentioned Doxygen, that's a great tool! You should look into it and write a small bash script that will automatically generate sources for the application you're developing in some tree structure you've setup.

One thing that I've haven't seen people mention is BOUML! It's fantastic and free! It automatically generates reverse UML diagrams from existing sources and it supports a variety of languages. I use this as a way to really capture the big picture of what's going on in terms of architecture and design before I start reading code.

If you've got the money to spare, look into Understand for %language-here%. It's absolutely great and has helped me in many ways when inheriting legacy code.

EDIT:

Try out ack (betterthangrep.com), it is a pretty convenient script for searching source trees:)

Answer 6

There really isn't a silver bullet other than just rolling up your sleeves and digging into the code.

This is where we earn our money.

Answer 7

Three things;

(1) try to run the test or example apps available, set low debug levels, and walk through logs. (2) use source navigator tool / cscope ( available both on windows and linux) and browse the code to understand the flow. (3) also in parallel use gdb to walk into code while running test/example apps.