Ask Slashdot: How To Start Reading Other's Code? 254
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."
Re: refactor, discard, repeat (Score:5, Interesting)
Find a function. Refactor it until you grok it. Discard the results.
Keep in mind that it will be VERY tempting to commit your changes, but you must throw away the work and chalk it up as a learning experience if you ever want to be taken seriously by the others who work on the project. Junior developers (and even some senior developers) often think they're doing everyone a favor by doing drive-by refactors, but they're not; they're just slowing down the entire team and coming across as that a**hole who keeps f***ing up the diffs and destroying the useful output of tools like git blame.
If you found any bugs in the previous step, make a patch with the absolute minimal change to fix each individual bug. IMPORTANT: Before committing the patch, first be sure that you can reproduce it in the old code, and that the test case is fixed by your new code.
Repeat the process until you understand the entire system.
With any luck, you will finish with a solid understanding of how the code actually works, and you will most likely also fix a few dozen bugs (if you didn't find at least one bug per kLOC, then "you're doing it wrong" or the code was written by an inspired genius with OCD). At that point, you will be the team's expert on how things work, and you will be in a position where you can start proposing simple refactorings that will improve the code quality.
Rewrite some parts (Score:5, Interesting)
Here is how I work on legacy code:
1) I don't look at the whole picture because there are too much details, so I prefer to attack little by little.
2) I quickly check what I can rewrite in order to optimize the code. If I have no idea, I run a profiler, and take a look at the routines that take the most time.
3) once I understood or rewrote the most consuming parts (sometimes it's heavily optimized, but most of the time, I can make a real improvement), I decide what most important functionality I would like to add, and I just focus on that.
4) if I really need to have robust code, I write tests for the routines before optimizing them, so that I can validate if there are regressions
5) whenever possible, I use "assert" and put some bound-checking tests, in order to validate the ranges of certain values or conditions.
The important thing is to start by taking ownership of a small part of the code, then a bigger part, etc... ... ?
Take one slice at a time, not the whole pie.
And one last point: knowing every little detail is useless, concentrate on what is important for you: performance, functionalities,
Since this is an OSS project ... (Score:5, Interesting)
Since this is an OSS project, can you suggest any tools similar to Understand that don't cost $995?
The only thing I could find was source navigator NG [berlios.de], but I have zero experience with it.
Re:Use the tools Borge (Score:4, Interesting)
Reading other people's code is a punishment that one must master if you hope to grow as a programmer.
So what is the reward for reading comments which are unnecessarily set in monospace type?
Re:Don't (Score:4, Interesting)
A person is a genius if he knows every nook and cranny of C++. But no one is expected to. Even just classes and objects are a fantastic addition over C, so there is really no reason to shun C++.
The problem is that taking C and just adding classes and objects would have been nice, but the changes in C++ go so far beyond that they can reach a perl-like level of syntax confusion.
Re:Start with the headers (Score:4, Interesting)
I maintain a huge C++ codebase written by someone else. Pointers are no problem at all. The structures and classes they point to are all defined somewhere. The problem is, after loads of features tacked on randomly, the code has become unmaintainable. Core features break other core features and ugly hacks abound. Also Microsoft's OLE library breacks because the original coder did some extreme use case things that expose a long unfixed bug in modern OLE32.dll libraries. Working with code like this leads to the conclusion, that once understood, sometimes it is better to reimplement the whole thing building in all the core functionality from the base.
This has been my practical experience with fairly well written C++ code. Comming from an embedded angle, there should be no problem understanding what the code does, or the data it works on, but maintaining or extending it may be a lost cause.