How to understand abstract(OO) source code?

Question

I explored in some open source projects and found it’s quite difficult to understand the sources. Nowadays, programmers tend to use OO design which leads source very abstract. I don’t mean they are bad, instead, I think the sources are beautiful and powerful but not easy to understand.

My question: Any advice or trick about how to understand abstract source code?

Ps: The projects usually provide ‘user manual’ instead of design manual. That is, the documents focus on how-to-use, not the design inside.

I don’t intent to join the projects or bugfix of issues. I just want to see how the authors build such splendid sources(mostly of).

Answer 1

My (very cheap) 2 cents.

If you use an IDE and import the source, there's going to be ways to finding instances of said class/method. So you can see where it was defined and used without having to waste time looking for it.

Netbeans: -if you hold ctrl and left click the method, it goes directly to where it was defined. -right click -> find usages, to show where it was defined and everywhere it was called.

Answer 2

Code reading and understanding is by far the hardest and most time-consuming part of a programmer's job. There's no easy way around it, and the documentation part is always quite sparse - not only in OS projects, au contraire...

There's no trick to overcome that. It's learning and hard work...

Thomas

EDIT:
Of course it is essential to have modern search & navigation tools as for example provided by Visual Studio and ReSharper. This lets you quickly see e.g. architectural diagrams of selected classes or examine class hierarchies.

Answer 3

Actually using a debugger to step through the code as it's running can be a very powerful method of seeing how a project works, and can give you a deeper understanding than just reading through the code.

From a functionality point of view, if there are unit tests with the project, they can give an insight into how various aspects are expected to work and the reasons behind some design decisions.

Thirdly, you could pick a subsection of the project and try to replicate it yourself using the original as a guide. That way you'll often be able to see why the designer made the decisions they did, and how the classes fit together.

Answer 4

There are various tools out there (i.e. Bouml), that can reverse engineer source code, meaning, you can generate UML diagrams out of source code.

Apart from that I would suggest, like Andy did, to step through the code with a debugger.

Answer 5

I think you have something backwards: abstractions are supposed to make code easier to understand, because you can think about it at a higher level, without keeping all implementation details in mind. Of course, this is often not done correctly.

Any decent project should provide API docs that, for each class, give at least a short, high-level explanation what it does. Additionally, there should be a "developer manual" that explains which are the core classes to start with. Code examples can also play this role.

If the project has no API documentation or cannot be understood despite having them, then chances are that it's not abstraction that's the problem, and the source is in fact not "beautiful and powerful", but an undocumented, badly designed mess better left alone. This is actually by far the most common case.

Answer 6

I suggest learning and knowing common design patterns. E.g. I noticed a lot of people have read the Design Patterns book by the gang of four but not really internalized it. I have looked up in it on many occasions and implemented many of the patterns, to the point were I am very familiar with most patterns.

When I look at other OOP code I often recognize the patterns from this book and it helps me a lot to understand the overall structure of code I am not familiar with. Also you should set up some indexing or referencing tool that lets you browse the code quickly. E.g. ctags or cscope with Vim, TextMate or use an IDE that lets you jump around.

After reading the book I suggest reading Cocoa Design Patterns. Now you might not care or need to use Cocoa, but it was designed in tradition of Smalltalk were design pattern originated and I think it explains a lot of patters stuff very well. Especially model-view-controller is explained better than anywhere else I have come across.