[Vereplys]

It would be great if somebody experienced would produce in-depth looks at parts of the source code.  For instance, if somebody could provide a detailed explanation of the graphics code, or the sound, ai etc.  it would help out amature programmers a great deal.

[vyper]

Hehe, fs2 source is one of the most monsterous bits of code ever seen  - who will slay this monster?

[penguin]

What he said...  We're all n00bs here.  

Most of it is reasonably documented, and organized logically.  Graphics stuff is in the Graphics directory, sound is in Sound, weapons are in Weapons, etc.  The graphics system is also fairly implementation-independent as well; D3D, OpenGL, etc. all have the same interface.  Look at 2d.h and some of the other .h files in the Graphics dir for the functions that are defined.

The downside is that it is not particularly object-oriented, so there are many dependencies and assumptions between unrelated modules.

And it's a fairly big project Did I mention that?

[Inquisitor]

I think there is a perception difference in this community, or, people simply have never been exposed to a large codebase before.

At least one person has referred to this as spaghetti code, and the more I look at it, the more vehemently I disagree with this assessment, and I call that inexperience with large codebases. This is a large, reasonably well organized, reasonably well documented, reasonably modular bit of code. The speed with which the first Linux port appeared speaks to it's modularity. Someone was able to follow it with a very abbreviated introduction to the code. It's not perfect, but it's far from unintelligible. But, I am just being a Volition butt-kiss here (I have so much to gain, professionally by telling Dave he's great :/).

Seriously, though, the things that are missing are flow charts etc. I'll look into some document generating software we can run, maybe autogenerate some of this material for the "uber" newbs, that is a very reasonable request. Thorough documentation is a learning mechanism, so, if anyone wants to help, please, speak up

Anyone sufficiently familiar with autogenerated documentation tools to give me a favored tool?

[daveb]

At least one person has referred to this as spaghetti code, and the more I look at it, the more vehemently I disagree with this assessment, and I call that inexperience with large codebases.

Bingo! Give this man a banana

To penguin :
As for not being object oriented leading to lots of interdependencies - I don't see how being object oriented would change this. In fact, game development is a very special case of "why OOP does not work all that well". The main reason is that properly done OOP requires tons and tons of pre-planning and design work before throwing the architecture down. But the nature of game design is that everything is fluid. Probably 80% of the time of a standard full-size project you're seeing constant overhauls and changes to the codebase as demanded by design. True, minimizing this is always preferable, but in my experience, OOP design tends to react less favorably to such dynamic demands. And when C++ reacts unfavorably, everybody has a bad day and the really heinous hacks start creeping in. Judicious usage of friend. private and protected members magically become public. Etc, etc. In the FS2 codebase I'd argue the most heinous code of all is the MFC meatwagon that is Fred. Oy.

There's also a good case to be made for many compilers (*cough*ee-gcc*cough*) really botching implementation of referenced operators and return values. All it takes is the compiler F'ing up your vector and matrix classes and you get a wonderfully silent 20% processing hit. Any HLL feature that requires that you skim generated asm code to make sure its not killing you isn't very "high level" IMO. Don't even get me started about templates

In fact, in every possible case where I've seen relatively hardcore OOP used in release software its resulted in far more ugly, rigid and mis-designed eyesores. Now, you could claim "you just don't know how to do OOP properly" and this may be true. But my counter-argument to that is twofold -

a.) OOP and C++ has a real mean tendency to fool people into _thinking_ they know how to do it right. Any jackass can go and write

class weapon {
};
class dagger : public weapon {
};
class spear : public weapon {
};



and then say "ha! I know how to use OOP!" - and then they proceed down the road to their own doom, tricked by Bjarne.

b.) Given the skill level of the people we have at Volition (for example), having to have some oddball training or special insights or other magic wisdom in order to use something "properly" without F'ing it up leads me to think "why the heck would I want to use it if there's such a danger of screwing up" (which there most certainly is).

Of course, I am looking at this from the perspective of a game developer who typically has to deal with alpha to pre-alpha compilers and assemblers (as with the PS2), horribly shifting design demands, and "exciting" schedules where hacks unfortunately, ship games. One too many clusterf***s of code design tends to make you a bit paranoid.

But I digress. OOP vs. non-OOP is a topic for the trolls at /.  

[daveb]

Seriously, though, the things that are missing are flow charts etc.

This, sadly is totally true. Being a very inbred kind of process, knowledge of how an overall piece of code the size of FS2 works is gained by osmosis for people just coming on.

About every 9 months or so, some programmer at Volition (usually a new guy, or an older guy who hasn't learned his lesson yet) posts something like "we should do code and system reviews".  All the senior guys groan inwardly as MikeK goes "hey, that's a great idea". 2 weeks later one system has been reviewed to a rousing round of golf claps and the whole process is promptly forgotten. In fact last time this happened, I bet Mike a box of donuts that in 3 months time, we wouldn't be doing the reviews. I won that bet quite handily, but the donuts were a moot point since we've started getting Dunkin Donuts every Thursday anyway (booyah).

I'm sure there's plenty of stuff we do that would make guys from IBM (there's an office next door to us) and other "real" companies shudder (just the other day I wrote a function called vif_collide_mesh_NEVER_CALL_ME(...).  I've seen other gems like find_room_slowly()  and  get_mesh_type_this_is_a_hack() ). The reason we get stuff done anyway is that (game) programmers tend to learn from their mistakes very quickly because each major mistake ends up consuming hundreds-to-thousands of hours of their lives at the end of every project during crunch time. The senior guys tend to be a little more, uh, _round_, but we're a lot more sly  

[Inquisitor]

Thanks Dave, now you have proved I am a V-buttkisser

Well, I am gonna rerun Doxygen here at home and upload the results to the CVS server, URL to follow, stay tuned.

[daveb]

Hehe.

I might be persuaded to write up an in-depth review of a system or two provided I can jar my memory enough to remember anything.

[LtNarol]

flow-charts would be really nice...just started learning c++ and i've taken a couple of looks at the fs2 code; having a hard time following some of it and even the parts i can follow i have no idea how to change to add those neat little things in the requested changes thread:doubt:

[daveb]

What would probably be just as useful as a system overview is a solid 3d math primer, especially as observed by the FS2 code. Hmm....

[Inquisitor]

Well, the first Doxygen run is on the released code, not anything we have been messing with, so, hang tight till that comes online.

Maybe that will jar the old memory as well

p.s.
craploads of math primers, page thru the resources at www.garagegames.com

p.p.s.
for the record, Dave, even the "big" companies sometimes don;t manage to pull off code reviews Same problem "that's a great idea! client wants this tomorrow!"

Mutually exclusive, sadly, sometimes, we get to do them, most of the time, it's on the fly, seat of the pants, etc.

[penguin]

Hiya DaveB, nice to see you again

My comment about the non-OO-ness ( I know that's not a word) of the code wasn't meant as a slight.  As you pointed out, it's a matter of reality in almost any large system, and especially with games, as the components are intertwined pretty tightly, and performance is a big deal.  But it is a large and frightening thing to look at if you're a less-than-experienced coder (and kinda scary if you are experienced )

As a Real World developer (for *mumble* years now) I can certainly appreciate the compromises one must take between the "design ideals" that the CS PhDs write about, and the code that must be shipped (2 weeks after the deadline has come and gone).  These days, 50% of the code I write is in Perl, the ultimate get-it-done-quickly language.  But I started out as an assembly programmer (I am old ), and I still find it surprising that many "professional" developers have no idea what the compiler spews out when they write a virtual method, and they are also the ones who wonder why the standard C++ iostreams library is so damn slow

Yow! I'm falling into slashdot mode too, sorry for the rambling.

Overall, I am very impressed with the readability with the code.  As Inquisitor pointed out, we had an almost-working Linux port a couple weeks after the source was released (working only nights & weekends, stupid day job), so that says a lot.  And my own ignorance of OpenGL is the main impediment to getting it done.  [But we haven't ported FRED yet -- that pinnacle of object-orientism as you pointed out ]

In the end, the final product is what counts, and the longevity of this game, and the dedicated fanbase, says a lot more than any design review.  You guys should feel damn proud, but you don't need me to tell you that.

(Can I join Inquisitor's :V:-buttkisser club now? )

[aldo_14]

Well, i think the code is remarkably readable...because I can understand bits of it.

Bearing in mind that my C is limited to 1 semester of low level programming - which was more concerned with assembler translation, that speaks a lot of it's documentation.... much as i prefer OO (Uni's most concerned with the concepts rather than speciifc code,so we use the 'easiest' langauge - Java), I like c and I can understand why it would be used... especially it seems easy (with knowledge) to use ofr optimising stuff.

I just hope i can learn enough next semester when I do graphics to actually understand some of this stuff properly.

[Vereplys]

For as well documented and readable as the source is, it is true that many people, such as I, are still rather green.  And when presented with this much c++, stare at their screens and say, "wha?"

I'm still an undergrad, I downloaded the code most so I could figure out how a big project works, and I think the in depths would be a good learning experience.

[Inquisitor]

Ver: See the Doxygen thread. Right now, that's going to be the extent of the documentation (and I haven't uploaded it yet) but anyone can download and run Doxygen, so that will give ya a head start