8 Replies - 835 Views - Last Post: 29 January 2013 - 08:57 AM

How do you go about understanding other (open source) projects?

Posted 28 January 2013 - 08:44 AM

I can easily understand single file projects or projects with just three or four files, but I'm trying to understand a bigger project (insight3d). I get that I have to understand the general flow of the program before looking at the individual functions, but I spend almost all my time just looking through the roughly 100 files for functions so that I can see where the program goes next or to identify which functions are helper functions. I don't think it's supposed to be this complicated. How do you guys get around these larger projects? Is there some piece of software I should have?

Replies To: How do you go about understanding other (open source) projects?

Re: How do you go about understanding other (open source) projects?

Posted 28 January 2013 - 09:22 AM

I would read through any system design docs and what not first. Lacking that then start with the constructor and start sketching out what is being used where. A few boxes, words, and arrows tend to be helpful.

Re: How do you go about understanding other (open source) projects?

Posted 28 January 2013 - 09:28 AM

Whiteboard. Draw maps. Try to make abstractions and groups. Try to find good names for the abstractions and groups: if you can name something well, that's a signal that you understand it to some extent.
Look at the inheritance structure - how are these files related?

Describe the code on its own terms: derive your description from the source, not from someone else's idea of how things ought to be designed.

Re: How do you go about understanding other (open source) projects?

Posted 28 January 2013 - 10:19 AM

Quote

I know I have to map it. But I can't even map it because all the functions are in different files and I can't find them.

Well.. I am not exactly sure if there is a special methodology or class you can take to shore up your 'search files for a name'... but I tend to make use of file searching utilities like 'agent ransack'.

Quote

When you say constructor, do you mean the c++ class constructor?

I guess but it doesn't have to be c++... over all I meant it the overall entry point into the app when it runs. The *APPS* constructor... not necessarily a random class's.

Re: How do you go about understanding other (open source) projects?

Posted 28 January 2013 - 07:22 PM

Although I now use SlickEdit as my primary text editor, I still go back to Source Insight every now and then because it has amazing facilities for exploring code. It's pretty good about letting you know where something is declared and where it is referenced. You can go down the path of references or declarations, and then undo the "stack" as you explore the code. SlickEdit also has this ability, and so does the new VS2012, but probably years of using Source Insight has made the experience more "natural" for me. Older versions of Visual Studio wasn't too good about undoing the stack unless you are very diligent about setting up bookmarks, but VS2012 seems to be better.

Another way to learn and explore code is to go through the unit tests. If you don't have architecture or design docs, the unit tests often given you a clue of how the components are supposed to act alone and in relation with other components.

Re: How do you go about understanding other (open source) projects?

I know I have to map it. But I can't even map it because all the functions are in different files and I can't find them.

The compiler manages to find them. Surely you're as smart as a compiler?

One way to find functions is to simply use the grep command. Start at the top of the file hierarchy you've downloaded and type grep -R functionName . If you get an error message, you're probably using windows. This is easily remedied: install a POSIX-compliant OS and restart from the previous step.

Another way is to start with some file and figure out what it requires, and start making your tree there. Continue examining files until a structure appears. Navigate that structure.

The point is, you want to figure this out - that's how you'll learn something. Just deploying a tool will not be nearly as useful, because you learn ten times as much by figuring something out as you do from being told it. It's frustrating, yes, but if you can't deal with frustration then you probably ought to look for something else to do with your time, because being a programmer will make you miserable.

Re: How do you go about understanding other (open source) projects?

Posted 29 January 2013 - 08:57 AM

1) Identifying the paradigm used first is key. It's hard to know where to start unless you know the paradigm. Step two requires knowing the paradigm, as the available design techniques depend on the paradigm.

2) Know your design techniques (or patterns, I'm avoiding that word as I don't want to give an overly oop approach to things... all paradigms come with their own design patterns/techniques for how people often organize and handle their code). If you don't know the design techniques/patterns standard to the paradigm in question... well you're going to be lost. The definitions for design patterns exist for many reasons, including acting as a list of names for complex structures so programmers can convey to each other easily how they've designed their project.

A program that follows the OOP pattern of MVC is easy to identify, and once known allows me to make several assumptions about how to navigate the code.

Here's the thing about these designs though. Usually when you learn them, you learn them AFTER the fact. You'll notice, "oh hey, that pattern there I just read about, I've been using it for years and just didn't know the name". They're designs not because someone created them, but because everyone just happens to use them. Not exactly, not identically to each other, but very similar. Code is a community effort, chaos colludes into order.

3) Start mapping out by looking at a group of code files and attempting to deduce what design technique they used. Start organizing it. If any sensible programmer worked on this project the file layout and everything should reflect the design they went with. From here the mapping should be simple.

You'll need unit tests and the sort to confirm any of your deductions when mapping it out. Design docs and code comments should also point you in the direction to confirm it. If the code lacks any documentation, comments, or anyting... well sorry, you're shit out of luck. I know I came into a job with a vb6 project was so huge they ran out of "namespace" for the variables (vb6 deals with variable names in a weird way I guess), and there wasn't a lick of documentation or code comments. And it was written by 15 different programmers, and integrated with a set of server side programs written in BASIC... I STILL haven't fully figured out how the whole thing works and I've been staring at it for 2 years. (well I've been doing other things as well)