Guidance for working with large projects

[moo]

Hey guys, this is my first post here (I just joined up). Obviously everyone here is really excited and there are alot of people that come here saying they want to contribute. So I guess this is just another one of those posts...

I have experience programming with both C++ and OpenGL. I've also done alot of 3D modeling and animation. However,

1.) I don't have experience working with an open source project

2.) More importantly, I don't have experience jumping into an already existing project as large as this.

My question is, what is your advice for beginning to work with a huge codebase like this? I've looked around the forums, maybe not carefully enough, but I don't really have a sense of how to go about beginning to understand how the code is organized besides spending weeks and weeks reading through the code. Is there a good approach to this? Or is there somewhere you can point me to which describes on a high level what is going on? Or any pointers on which sections are best to start with?

I understand I need to start small and try to work on patching minor issues that don't require knowledge of the entire codebase, but my intentions at this point are to contribute something substantial enough to require understanding of a sizable portion of the code that's already been written. So basically, I need to learn at some point how to understand all this. I'm interested in really committing some time to this project this summer and beyond, so your help (hopefully) won't go to waste. Right now, I'm pretty limited by my inexperience with large codebases.

So... any advice/references/guidance?

[Zoomastigophora]

The wiki has some high level conceptual stuff on the organization of the engine, which can help orient you, but otherwise, best you can do is read the code and read the comments (or generate the cpp-doc/look at the cpp-doc on Trac). I find Visual Studio's caller graph and class diagram generation abilities immensely helpful when trying to figure out how thing's are interacting.

[Jeru]

See extensive documentation on our Trac, and especially the tasks labeled "simple" to get your hands dirty.

Ask lots of questions. Even if they might seem silly. Our programmers love to help contributors out.

[Ykkrosh]

When I first joined this project it was already quite daunting - there's a huge amount of things interacting in lots of complex ways, and there's never enough documentation to get a good high-level view of everything. And it's grown quite a lot since I first joined, though I think it's also somewhat cleaner and better documented and better tested now.

A few random thoughts:

* A good IDE helps - I really like Visual Assist X since it makes it easy to navigate code (jumping to definitions, seeing expansions in tooltips, using autocomplete to find available methods, etc) and it seems fast and reliable even when the code is doing pretty complex things. (Then I moved to Linux and now use Eclipse and ack, which is nowhere near as nice for this.)

* Don't assume that all the code is well designed or well implemented - some is overly complex, some is obsolete or redundant, some is buggy, etc. Everything was done for a reason, but it may not have been a good reason or it may not be applicable today. So don't be fazed by seemingly crazy code - see if anyone can explain it, but then you might just have to accept it and ignore the problems (or, ideally (with sufficient time and confidence), fix it )

* I like tests - if you're not quite sure how a piece of code works, sometimes it's good to write test cases for it, since that lets you run the code in isolation without the rest of the game engine interfering. (Also it helps find bugs and prevent regressions, which is always good). So the test writing process is probably a useful thing to learn.

* Most of the engine isn't doing anything very novel, so you can probably find similarities with other libraries or with published articles which give a better high-level description of the underlying concepts - that's easier than trying to reverse-engineer the intended behaviour from the code.

* The engine is largely complete (though far from being finished), so there aren't many easy standalone tasks (they've mostly been done already) and most work will involve interacting with big chunks of code that are already there. So it's not going to be easy to dive in - I think it needs a lot of patience, and a desire to learn about everything (from low-level C++ details to high-level architectural designs), if you want to understand it deeply and do significant chunks of work on it.

* It's only ~200K lines of code (and half of those are comments or whitespace), so it's not really that large for a game or for an open source project . It's a big step up from a single-developer hobby project, but it isn't an unfathomable monstrosity (it's not OpenOffice or GCC; it's not even Doxygen) so you shouldn't be put off unduly

Trac has lots of information, though be careful that some of it is inaccurate or obsolete. E.g. the new simulation system (which I've been rewriting recently) has some high-level documentation that's still reasonably accurate; the old entity XML documentation is all wrong now. The GUI documentation covers the early design which is still mostly followed but there's been various extensions and changes. The graphics code has never been documented much. I don't think the networking code has ever been documented. Other parts of the code are in various states of documentedness. I guess it's good to scan through most of Trac to at least see roughly what's there, and then ask (on IRC or forum etc) for pointers on anything else.