Looking at medium scale projects and understanding their source code tips

[brokenbot]

Hi, I'm just diving into looking at source codes for a medium sized projects. The source is perplexing. I'm going to just start reading it now... but I'm looking for tips and suggestions about reading and understanding it.

I'm thinking of things like having a separate ppad open to paste variables and their meanings etc.

Is their a source documentation that helps explain its source etc? Or is the norm or standard to just RTDS?'

This is like my first source i'm reading that isn't from this site and is an actual project btw

[brokenbot]

i THINK I'M GOING TO MAKE A SMALL PROGRAM THAT JUST RECORDS MY NOTES ON AND RETRIEVES IT.... i Can type function blue.... the output... blue function is a function that prints the word blue

[andywestken]

What do you mean by a medium sized project?

When I start with a new project, I will look for the documentation. Whether it exists or not is up to the people who wrote the code, but I would expect there to be at least a description of the application, an overview of the design, and a list of the modules and their responsibilities. But you're talking about an orphaned open source project, all bets are off!

If you can compile and run the project, I would do so and try stepping into the code to find out how it starts up. I would start off looking at the main app and how it uses the other modules.

If there are tests, they would be another useful starting point.

If not already provided, I use Doxygen to create documentation, having ensured the config has CLASS_DIAGRAMS = YES. Even if there are no comments, Doxygen can extract the relationships between the different classes.

Andy

Doxygen : http://www.stack.nl/~dimitri/doxygen/
GraphViz : http://www.graphviz.org/
(If you're using Linux, these should both be available via your distro's repository)

I change the following config file options (cf. defaults in auto generated file) to extract as much info as possible.

PROJECT_NAME           = <your project name>
PROJECT_NUMBER         = <your project id>
OUTPUT_DIRECTORY       = <your output directory>
BUILTIN_STL_SUPPORT    = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
SHOW_DIRECTORIES       = YES
WARN_LOGFILE           = <your log file path>
INPUT                  = <list of directories/file to process>
FILE_PATTERNS          = <could leave blank for default behaviour, unless there are unusual file names/extenstions>
RECURSIVE              = YES
SOURCE_BROWSER         = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
GENERATE_TREEVIEW      = YES
SEARCHENGINE           = NO
GENERATE_LATEX         = NO
PDF_HYPERLINKS         = NO
USE_PDFLATEX           = NO
HAVE_DOT               = YES
UML_LOOK               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

doxygen --help -> to get help
doxygen -g to generate blank config file

The generated config file includes comments explaining the different options. See the Doxygen web site for more info. I am using 1.6.1 at the moment, so the options might now be a little bit different.

[brokenbot]

I was actually thinking about making a program like that... not as sophisticated though. Just records function names etc and details surrounding them(comments).