[Mongoose]

I took a couple semesters' worth of C/C++ courses in college, and for a few years now, I've thought that I should really attempt to delve into the codebase and see if there's any small way I could lend a hand.  Granted, I've probably forgotten as much from those classes as I still remember, particularly in the higher-end realm of classes and such, but I could probably still pick my way through most of the basics.  So when Goober posted this suggestion, I thought it might be something that I could take a serious look at.  I got MSVC all updated and such, eventually figured out what I should be searching for in terms of the skybox functionality, started opening files, and...well...

What got me was just how many places this analogous skybox rotation code popped up in the codebase.  You have the basic function in the starfield code, the actual SEXP code that implements it in FRED, what I'm assuming is the contextual FRED help, some other piece of code relating to FRED, one or two others, and all of the associated header files.  There were one or two references that I realized wouldn't apply to jump node rotation, but the rest of it referenced each other in a few ways I wasn't quite able to discern, and I also wasn't sure if there was some additional element that didn't have an analogue in the skybox rotation that I would have to add.  On top of that, with just an Express copy of MSVC, I wouldn't be able to compile a FRED build and properly test out what I was writing in the first place.  At that point, I figured that this was something I probably wouldn't be able to handle.

So I guess my question at the end of the day is how any of the team members initially managed to get a handle on the general structure of the codebase, and exactly how its main components are referenced by each other.  The most complex project I ever accomplished on my own consisted of only 1000 lines or so in a few files, with maybe one header file associated with the whole thing.  I've never taken on anything remotely as big as the FS2 codebase, much less come into it as an already-existing entity that's been worked on for years.  Do you guys have any advice for taking those first few fumbling steps?

[The E]

Speaking only for myself, I can say that wrapping your head around the way the engine is structured is a task that takes a bit of time. Back when I started looking at the code, which I think was in the time leading up to 3.6.10, I frequently bounced off it while trying to build a mental model of how things fit together. The way I went about it, and which finally lead me to success, was by looking at Mantis and picking an issue that sounds simple, then trying to concentrate on fixing that issue. Now, the important part is to not give up when it turns out that the trivial bug you were chasing was in fact one of Codethulhus' tentacles (May his semicolons always be placed correctly), but to press on and take notes along the way. Once I did that, I was able to piece together a mental model of the code and get a feel for the conventions by which it is organized.

[Iss Mneur]

Personally, I learned (what I know) of the code base by just diving in and trying to figure out how the engine interacted with its environment as a result of writing wxLauncher.  It basically snowballed from there, someone would ask for something and I would go spelunking through the code looking to find how it was implemented.  Did I always find it? No. But I didn't fail to find the code or fail to implement the feature, I just found where it was not .  I still need to do this because I am not intimately familiar with most of the code base. Haveing said that, I have spelunked through enough of the code to have a highlevel model of how basically everything works, but I could not tell you where specific things are implemented, except for a few specific things.

Basically search is your friend.  Most of the features have a comment near them that calls them by name, or more likely it has a table entry and in which case you can just search for the keyword and you will find the parser.  From there you can see what the parser does with the data which then lets you find the code that uses that data that the parser sets.

The code is also split into modules and major features are split into files (in general). The function names are usually helpful if sometimes inconsistent.  The name of the feature in code is usually but not always the same as what it is called by the tables or elsewhere.

[Swifty]

Here's the "best" way to figure out how the engine works.

Look at obj_move_all(). There is a loop that goes through every object in the game. Every object goes through a journey in this loop every frame which will dictate it's actions and movements. Just remember how ships in Freespace behave and try to correlate that behavior with the code you're reading as you go through that loop.

That's just the simulation part. Graphics is run by game_render_frame(). If you want an even greater picture of how the engine works, game_frame() is the greater function in which every gameplay frame runs through.

The issue is knowing where to start. That and reading and picturing the behavior you see during runtime with the code you're seeing before runtime.

[z64555]

Somewhat related...

MSVC has two useful search functions that can look through the entire solution, the currently active project, or the currently active document.

Both search functions may be accessed by highlighting the token (function or variable name) you want to look for. If any matches are found, it will display them in a popup window.

The first is "Find All References," which is essentially a glorified "Find" function. It finds all matches to your highlighted token, and can be used to track down a comment or two. It outputs anything it finds in the "Find Symbol Results" window.

The second is "View Call Hierarchy." This is a particularly useful function when you need to track down where a function is used, so you can get a better idea of what its significance is. It outputs to the "Call Hierarchy" window, and displays a binary tree which allows you to navigate through both the callers and callee's of any function that's involved with your selected token. This only works on functions, and not variables or comments.

[Mongoose]

Here's the "best" way to figure out how the engine works.

Look at obj_move_all(). There is a loop that goes through every object in the game. Every object goes through a journey in this loop every frame which will dictate it's actions and movements. Just remember how ships in Freespace behave and try to correlate that behavior with the code you're reading as you go through that loop.

That's just the simulation part. Graphics is run by game_render_frame(). If you want an even greater picture of how the engine works, game_frame() is the greater function in which every gameplay frame runs through.

This was actually one of the things I was curious about.  I know absolutely nothing about graphics coding and doubt I'll ever delve much into it, but I did want to see if I could find the "main" function that fundamentally drives what's happening on-screen.  I'll have to take a look.

MSVC has two useful search functions that can look through the entire solution, the currently active project, or the currently active document.

Both search functions may be accessed by highlighting the token (function or variable name) you want to look for. If any matches are found, it will display them in a popup window.

I did pick up on the general reference search, but I'll definitely have to try out the hierarchy version.  That sounds like it's just what I'd need in this instance.

Anyways, thanks for the advice everyone.  Maybe I'll take another crack at trying to figure out this feature.

[karajorma]

The second is "View Call Hierarchy." This is a particularly useful function when you need to track down where a function is used, so you can get a better idea of what its significance is. It outputs to the "Call Hierarchy" window, and displays a binary tree which allows you to navigate through both the callers and callee's of any function that's involved with your selected token. This only works on functions, and not variables or comments.

I hadn't used this one before. I always did it manually using Find All References. It's called the Call Browser in 2008 apparently but it is much easier than the way I used to do things.

[Nuke]

i know poking around inside the game engine gave me some pretty useful insights into game engine development and general coding. so its certainly a worthwhile excessive. even if you dont produce much in terms of code changes and bugfixes.

[madwax]

Hi I'm getting to know the codebase as well. I'm keeping up to date with svn head but I have few questions and I hope people might be able to help me.

1. The M$VC project have a number of differant configs for debug and release.  I read on the Wiki the inferno's are defaults, is that still the case and which of the SS/SS2 are defaults.  I only have a copy of Diaspora which I have cp into place and run, you got me hooked with Diaspora.

2. The codebase is very much C based but I've read and seen a move towards more C++ (using stl and classes).  Is this the general direction? I've been around doing C/C++ for a long time and the days of the C++ compilers being next to junk have long gone. I'm not taking about rewriting things just more a question of "style"

thanks

Mad Wax....

[niffiwan]

1) inferno builds are the default now, and SSE2 builds (on windows) are the default now as well. 

2) In general I'd say we're moving more towards a C++ style than plain C. 

And...

[z64555]

Hi I'm getting to know the codebase as well. I'm keeping up to date with svn head but I have few questions and I hope people might be able to help me.

1. The M$VC project have a number of differant configs for debug and release.  I read on the Wiki the inferno's are defaults, is that still the case and which of the SS/SS2 are defaults.  I only have a copy of Diaspora which I have cp into place and run, you got me hooked with Diaspora.

2. The codebase is very much C based but I've read and seen a move towards more C++ (using stl and classes).  Is this the general direction? I've been around doing C/C++ for a long time and the days of the C++ compilers being next to junk have long gone. I'm not taking about rewriting things just more a question of "style"

thanks

Mad Wax....

Welcome to HLP!

1. Your Solution Configuration can be found in the MSVC tool bar, usually right next to the Green Arrow used for "Start Debugging." If you have an Express versions of MSVC, you will need to expand the drop-down lis and then select the "Configuration Manager" at the very bottom. Once there, empty the checkbox in the "Build" column right by Fred2.

This should prevent MSVC Express from trying to build FRED along with FSO, and therefore prevent MSVC from complaining that it can't build FRED (because the Express versions doesn't have a particular MS resource that the paid versions do).

2. The code base is trying to be moved into C++ and as much object oriented practices as feasible. This is because C is somewhat difficult to maintain, and the sheer amount of data floating around in the engine would make anybody cry if they tried to take it all in at once. OOP allows individuals and freelancers to work on only the bits that they want to work with, and not fight with the codebase trying to find which thread function they need in order to work with a particular data structure. The indent style is a mixture of K&R 1TBS and Allman, but most new code prefers to use Allman style.

General rule right now is "If you didn't change any actual code functionality, then don't change the indent style" for all patches. Reason being, this allows the SCP to quickly evaluate your .diff's and .patch's without needed to go through all the "indent fluff." I learned that the hard way.

[madwax]

Thanks z64555 and niffiwan,

Thanks for that.  Stopped using the "debug" config now, well after having to in increase the value of MAX_PATH_LEN (why was it 128???) due to my folder structure. 

I have worked on a number of very large codebases over the years (now I feel old) and FSO is not too bad.

Mad Wax....

[karajorma]

The indent style is a mixture of K&R 1TBS and Allman, but most new code prefers to use Allman style.

It shouldn't.

You shouldn't be using Allman style at all. The reason for a lot of newer code having that style is because we didn't bother too much with style rules when the SCP started. But eventually we came to the conclusion that we should try to be consistent. Cause having multiple styles is just confusing.

And believe me, I'd rather be using Allman style myself.

[Iss Mneur]

2. The code base is trying to be moved into C++ and as much object oriented practices as feasible. This is because C is somewhat difficult to maintain, and the sheer amount of data floating around in the engine would make anybody cry if they tried to take it all in at once. OOP allows individuals and freelancers to work on only the bits that they want to work with, and not fight with the codebase trying to find which thread function they need in order to work with a particular data structure. The indent style is a mixture of K&R 1TBS and Allman, but most new code prefers to use Allman style.

No.  You are correct that we are drifting towards C++ and a C++ code style, but the reason you state is wrong.   Simply wrong.

The reason we are drifting that way is only because that is what our members know, not because of any reasons that you cite.  Object Orientated Programming is not enabled by a language (though it can be made easier by language features).  The best example of a heavily used, modified, and adapted object orientated code base is the Linux kernel.  It has a strict object oriented design that is implemented entirely with macros and the GNU C compiler.

It may surprise many, but FSO is and always has been Object Orientated, even though it is implemented primarily using plain C language constructs.  It even uses inheritance, but you don't really see that directly either because most of the work that is done on FSO is from the inside.  So, to use a tired phrase, you can't see the forest because of the trees, or more aptly, you can't see the objects for the C .  I note that I missed this design when I first started with this code base myself, it was only something that dawned on me later.  Anyway my point is, FSO managed just fine without using most C++ features for most of its life, so don't feel obligated to use C++.

The rule is, use the style that is there already. The existing styles (as Karajorma noted) are all over the place, I personally also like the Allman style but it is not the style that is used by most of the code.

Also. FSO is single threaded.  This has nothing to do with the language.  And it certainly has nothing to do with design paradigm. But it is a design choice from 1995 that was perfectly valid for a game until about 5 years ago and is still used to great effect today;  a single threaded design does have the advantages you note however.

General rule right now is "If you didn't change any actual code functionality, then don't change the indent style" for all patches. Reason being, this allows the SCP to quickly evaluate your .diff's and .patch's without needed to go through all the "indent fluff." I learned that the hard way.

This rule will probably never change.  Just like The Cardinal Rule.

Thanks for that.  Stopped using the "debug" config now, well after having to in increase the value of MAX_PATH_LEN (why was it 128???) due to my folder structure. 

Because core of this engine was written >15 years by a company and it has a tendency to do odd things when you change constants.  Primarily the result of more that one dummy reusing the constant because happened to be the same as what they wanted. Or they magic numbered the constant in in at least one place.

I would suggest rethinking your folder structure unless you want to go down that rabbit hole as your first "project"... 

[Mongoose]

The indent style is a mixture of K&R 1TBS and Allman, but most new code prefers to use Allman style.

It shouldn't.

You shouldn't be using Allman style at all. The reason for a lot of newer code having that style is because we didn't bother too much with style rules when the SCP started. But eventually we came to the conclusion that we should try to be consistent. Cause having multiple styles is just confusing.

And believe me, I'd rather be using Allman style myself.

I didn't realize how many indenting styles were out there until I just looked at the Wiki article, though given how long hardcore programmers have been fighting over two derpy text editors, I suppose I shouldn't be surprised.  I guess the style I used back in school was probably GNU by default, since the Comp. Sci. program's editor of choice was emacs.

[madwax]

I didn't realize how many indenting styles were out there until I just looked at the Wiki article, though given how long hardcore programmers have been fighting over two derpy text editors, I suppose I shouldn't be surprised.  I guess the style I used back in school was probably GNU by default, since the Comp. Sci. program's editor of choice was emacs.
[/quote]
indenting style is just the tip of the ice berg    20 year of coding and I've been drawn into more coding style debate than anything else (when it comes to C/C++)

I would suggest rethinking your folder structure unless you want to go down that rabbit hole as your first "project"... 

Trust me I like going down rabbit holes 

Mad Wax....

[Iss Mneur]

Trust me I like going down rabbit holes 

Mad Wax....

That is good. We have a lot of them.

[Valathil]

F12 and "Find all references" are your best friends in MSVC. Then just do things like "when a player fires a weapon what happens" then find someplace thats involved in that. Then trace forward and backward. Learn how it works then pick another task like "a ship gets rendered to the screen". Repeat that for about 20 or 30 times and you should get a feeling for where everything is and how its done. Thats how I learned it. You know you're getting somewhere when you hear a bugreport and think "oh that could be faulty logic in some_function in some_file.cpp"

[Mongoose]

I think I am about ready to attempt digging into this particular issue again, but I've come up with one more question before I started on anything concrete.  In terms of generating actual new code, what's the best way to go about integrating it into the existing SVN checkout?  Do you guys initially code right into the existing files, or do you write things up separately in their own file, and then paste them in later?  And if you use the first route, does VC++ have any sort of built-in diff/patch functionality that would differentiate your additions to the code?  I know the answers to these questions probably depend on whether or not one has SVN write access, so I'd obviously be coming from the "not" side.

[karajorma]

I think I am about ready to attempt digging into this particular issue again, but I've come up with one more question before I started on anything concrete.  In terms of generating actual new code, what's the best way to go about integrating it into the existing SVN checkout?  Do you guys initially code right into the existing files, or do you write things up separately in their own file, and then paste them in later?

Definitely the latter. The former is far more trouble than it's worth.

And if you use the first route, does VC++ have any sort of built-in diff/patch functionality that would differentiate your additions to the code?

http://ankhsvn.open.collab.net/

Basically allows you to do all your SVN needs right from inside MSVC. I still tend to use Tortoise mainly but it's nice to have that functionality there when I need it.