How to get the structure of software if there is no document?

Question

I am reading a project code, however there is nothing but some .cpp and .h source files.

How can I get started and get the structure of the software?

Answer 1

The header files will give you the classes that are being used in the application. Search the code for "main(" to find where the program starts and begin following the code from there.

Answer 2

2 choices:

1. Pick a class and start mapping out from that what it uses. Build up a map of the data structures this way and if you want you can also delve into the function call flows to build up some form of sequence diagram
2. Grab a tool that will do the above for you. Enterprise Architect can do this for class diagrams. Be warned that these tools are frequently fairly expensive.

Answer 3

Use a document generator like Doxygen - this will create a navigable web of hyperlinks to your code.

Answer 4

Another thing you may be able to do is to use a tool like Sparx Enterprise Architect to reverse-engineer the code. It will produce a UML model and diagrams of the classes contained in the files. Relationships between the files can then be seen.

Answer 5

G'day,

Have a look at Diomidis Spinellis's excellent book "Code Reading" (sanitised Amazon link) which covers all sorts of techniques for getting into someone else's code.

Edit: What sort of size are we talking here? 1 kSLOC? 1,000 kSLOC? Just do a recursive grep for trailing semi-colons to get a feel for the size.

And how many files?

Techniques will vary greatly depending on the size.

HTH

cheers,

Answer 6

I depends on what is your goal (debuging, rewriting, just undestanding, ...), but here is one way to do this : refactor and comment the code as you go through it. It other word, start from the bottom and go up.

It work - I do this every day ...

Answer 7

If you're using windows, then playing around with a great IDE like Source Insight can be helpful.

It has plenty of features for visualizing the code flow that can help. Check out the features page.

p.s., I am not affiliated with them in any way.

Answer 8

Personally, I have found source navigator NG to be very useful when facing a completely new code base, it's a freely available open source project specifically meant to be used for this purpose of navigating a new code base:

source navigator NG is a source code analysis tool. with it, you can edit your source code, display relationships between classes and functions and members, and display call trees. you can navigate your source code and easily get to declarations or implementations of functions, variables and macros (commonly called "symbols") which helps you discovering and mapping unknown source code for enhancement or maintenance tasks.

Source Navigator NG is based on the original Source Navigator project:

Source-Navigator is a source code analysis tool. With it, you can edit your source code, display relationships between classes and functions and members, and display call trees. You can also build your projects, either with your own makefile, or by using Source- Navigator's build system to automatically generate a makefile. Source-Navigator works with the Insight GUI interface for GDB. Source-Navigator supports C, C++, Java, Tcl, [incr Tcl], FORTRAN and COBOL, and provides > and SDK so that you can write your own parsers. Use Source-Navigator to:

• Analyze how a change will effect external source modules.
• Find every place in your code where a given function is called.
• Find each file that includes a given header file.
• Use the grep tool to search for a given string in all your source files.

Also, to get a good understanding of the basic calltree during startup (i.e. the initialization procedure), you may want to consider using gprof or callgrind (valgrind).

In addition, I would recommend to directly start commenting the source code yourself, i.e. by adding plain text files to each subfolder, describing the contents of each code directory, the purpose of each individual file and basically everything that's useful from a high level point of view to grasp the project's overall structure, so that you can basically refer to some form of 'index' file detailing the internal structure of each source code folder.

This will help you to easily know where to look for certain things.

Similarly, augmenting the source code with such comments detailing the scope/purpose, and description of each file is also very useful.

Personally, I also try to document important APIs, preferably using a syntax that is well supported by source code documentation tools (e.g. doxygen), so that documentation can be easily created automatically.

Additionally, I try to extract common snippets of code from a code base and save them separately for later use, so that I can largely copy/paste code and simply customize it.

Besides, if there's no formal issue tracking facility being used, I also find it very useful to add issue-tracking files to each folder, in the form of:

• BUGS or ISSUES
• RFEs or IDEAS
• TODO
• CLEANUP

If you are working with multiple developers, you may also want to add files such as the following to each folder:

• README
• AUTHORS
• MAINTAINERS
• ChangeLog

Depending on the complexity of the component/folder, you may even want to add files for additional information, such as:

• DESIGN
• PLANS
• IDEAS
• FAQ

This will make it easier for people to get an understanding of each component, and determine who to contact in case of questions.

Ideally, you'll be able to talk your fellow developers into helping to maintain these various files, this can be a really great help because very quickly, you end up with useful information, that you can easily use to create documentation with a high level view of the project (for example by automatically convering all files to a PDF file).

People will actually see how useful and easy this is, once they see an automatically created PDF file for the first time.

Just by collecting all your notes within the actual source tree, maintaining it using SCM and by encouraging fellow developers to help with this, the quality of your documentation is likely to improve rather soon.

If you are primarily developing on windows, or creating cross-platform software, you'll probably want to use a standard *.txt extension for these files.

On the other hand, if all of this shouldn't be feasible -for whatever reasons- in your situation, at least set up a central wiki so that all developers can document their knowledge and key questions centrally and easily.

But honestly, I've tried that before and know for a fact, that most developers more easily and more comfortably deal with source code and other files in a repository than with wikis or even source code documentation that's separately stored using wikis.

Actually, this is another case where a wiki frontend to source code documentation would make a lot of sense. Unfortunately, nothing like this exists so far, to my knowledge.