Ask Slashdot: How To Start Reading Other's Code?

BorgeStrand writes "I'm reviving an open source project and need to read up on a lot of existing code written by others. What are your tricks for quickly getting to grips with code written by others? The project is written in C++ using several APIs which are unknown to me. I know embedded C pretty well, so both the syntax, the APIs and the general functionality are things I wish to explore before I can contribute to the project."

Unit Tests

[Anonymous Coward]

If possible, I would try writing unit tests for the existing code. This tests your understanding of what you are reading and will come in handy later if you change the code. If unit tests already exist then I suggest that you read them since they will tell you the intention of each function.

Doxygen

[mapinguari]

Even without Doxygen's specific format for comments, you can use it to graph object relationships, call-trees, etc.

You can generate docs limited to a few files or classes if you just want to focus on them.

www.doxygen.org

pretend you are the computer

[Laxori666]

First, figure out how the code gets loaded and runs. Find the equivalent of the 'main' function. Then start tracing it, seeing what functions get called, how things are loaded, etc. What really helps here is an editor you can CTRL+click on a function on to go to its definition. When you hit a function that doesn't call any other unknown functions, then you can start understanding what it does without having to step into it. These are the basic functionality units. Then when you know enough of those, you can start going a level up, etc. Eventually a picture forms in your mind of just how things work. You can optionally skip over functions for preference of looking at them later if it seems pretty clear what they do based on the name & how they're called, but you might find important stuff in there later. This is how I go about it, anyway. It can be very frustrating and very confusing at first, but eventually the picture starts making sense, then things click in a most satisfying manner. That being said, the above is also the reason I can dislike complicated frameworks. There's so much indirection that it can take quite a while indeed until you hit something concrete. The mark of a good framework is, either it doesn't do that, or it does but soon enough you figure out its parts and then you can treat it intuitively.

Re:How to read code

[cdp0]

Are there tools that do this automatically?

Have a look at Scitools Understand [scitools.com].

Stackoverflow, CodingHorror

[Anonymous Coward]

Read this: http://stackoverflow.com/questions/3586073/reading-others-code [stackoverflow.com]

Also: http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-luke.html [codinghorror.com]

CCVisu

[PLAST]

You can use doxygen to create a dependency graph and visualize it using CCVisu.

http://www.stack.nl/~dimitri/doxygen/
http://ccvisu.sosy-lab.org/
http://ccvisu.sosy-lab.org/manual/main.html#sec:input-dox

Re:How to read code

[stephanruby]

For me, if I can't understand code written by someone else (which happens much more frequently than I care to admit), I'll do a spike and I'll try to rewrite the core functionality from scratch. Now don't get me wrong. This doesn't mean that my code will be half as good as the original implementation, in fact, it won't be for sure, since I won't spend much time on it. For me, that exercise is just a way for me to initially orient myself (and I do not keep the code I write during that phase).

If I'm lucky enough to have a good original version history of the code base, I'll go and pull up the original 0.1 version of the code (while I'm doing my own rewrite). Even if that version of the code is completely wrong. It still has a much higher chance of being something I'll understand. And then, I'll have a better understanding of what the developers were trying to do in the subsequent evolution of the project. Then, I'll isolate the parts of the latest code base I can safely break without breaking the entire thing, and I'll focus on those parts first.

Of course, during that next phase, I'd like to say I write unit-tests for the parts I modify before I modify them, but that's usually not how I work. I'll often have to fall down flat on my face a couple of times, cry in pain and frustration, and tear my hair out, before I'm willing give up and go back to doing things properly with unit tests. This does happen quite frequently, because I never seem to learn my lesson.

And of course, like someone else said already, I will also draw all kinds of mind maps and doodles throughout the entire process. And also, if I have access to one of the original developers who wrote the code, that's even better. If I can pair program with one of those persons, that's the ideal. If I can't, then talking to that person is the second best alternative. That person will be the best person to know all the weak points of his code base, give you a thumbnail overview of the architecture, and he will also be the best person to point out what parts you can work on first (so that you can gain confidence and a gradual understanding) that are the least likely to break the entire thing.

Re:Test and Break

[mooingyak]

Also, vowels apparently used to be very expensive in C variable names "back in the day."

Certain early C implementations would only use the first 8 characters of a variable name. At that point, the vowels are usually the most expendable when coming up with names.

Re:Maybe.

[Endophage]

There are plenty of design patterns other than MVC and depending on the particular application, MVC may not even be applicable.