Jump to content
  • Advertisement
Sign in to follow this  
stromchin

Reading someone's code

This topic is 2575 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

My company made a game before I started working there. And now they are making a new one kind of similar to it.

So I will be mainly in charge of it (it's not that the game type is too complex or anything), I've been told to read and understand the code, but there is barely any comments on it.
Using visual studio 2008, I made class diagrams (which help only a little bit)
and read the code many times, understanding the finer c++ things that I didn't know before. And then trying to understand what different classes are supposed to do.
I basically come from "school knowledge" so for example, I was never taught scripting for games... and this game is heavily scripted, so I'm having trouble with that.
And in general with the flow of the game.

My question: besides reading and debugging and tracing the code in the debugger... what else can I do? This is my task until the other guy finishes putting together the base for the new game and hands that to me. I just want to be more prepared (first time with so much responsibility) but I dont know what else I can do.

I wish each class had a comment explain what it's supposed to be doing, or who is supposed to call it.
I can probably end up copying a lot of the stuff for the new game, but I want to understand what I'm doing instead.

I don't think the level is too high for me, but what I think is that without comments, it's really hard to interpret someone else's code from 0 without any kind of comments or documentation.

Share this post


Link to post
Share on other sites
Advertisement

My question: besides reading and debugging and tracing the code in the debugger... what else can I do?


Sometimes documentation can be a bad thing i.e. when it is incorrect. If I were you I would look into some kind of automated tool that could parse the code and show you its static structure preferably in a graphical format. Knowing the class hierarchy, the dependencies, and any tangles from a high level would go a long way in helping you determine what the heck is going on.

Share this post


Link to post
Share on other sites

[quote name='stromchin' timestamp='1306737396' post='4817409']
My question: besides reading and debugging and tracing the code in the debugger... what else can I do?


Sometimes documentation can be a bad thing i.e. when it is incorrect. If I were you I would look into some kind of automated tool that could parse the code and show you its static structure preferably in a graphical format. Knowing the class hierarchy, the dependencies, and any tangles from a high level would go a long way in helping you determine what the heck is going on.
[/quote]

that's a good idea. I don't know much about that, but I've heard about doxygen. Is there a better tool for it?
I think doxygen might not be exactly what I want though...

update: ok, I used doxygen on it, and it helps a bit. At least as a way to see classes in a more organized way.

The problem with this code is that there isn't much inheritance and stuff like that. Just a bunch of classes dispersed everywhere, so the diagrams generated don't seem to help much. But thanks, I'll keep looking at the code with doxygen a bit more and see if I can get a better grasp of this code.
Other than that, I'm pretty bored :unsure:

Share this post


Link to post
Share on other sites
Thanks, I think I saw something that's a bit of a performance problem at some point (the hardware can still take it, but I think I can optimize it)... I guess I'll try to fix that.


1) First, always make sure that there doesn't exist some documentation that you don't know about. Ask people who are familiar with the code or former programmer if there exists some documentation that you haven't been given yet. Sometimes you'll get lucky, but don't get your hopes up.
[/quote]
I already did... and nothing. It's like: "the code is there, what else do you need?"


2) Use auto-documentation tools. It sounds like you've already done this with Visual Studio's class diagram (I'm unfamiliar with VS though). I typically run the entire source code through doxygen to generate class diagrams, dependency graphs, class/functions/variables/constants lists, etc. It won't do too much to help you understand the code, but it is useful in organizing things and providing a "reference index" of sorts.[/quote]
also just tried it, and it's good... but it can't make miracles happen... at least it gave me a better "view" at some of the classes.

3) As you go through the code, add comments as you figure pieces of it out. Don't just sit there and read through thousands of lines and try to make sense of it all. its boring and non-engaging, so you'll quickly lose focus or forget what you read through 100 lines ago.[/quote]
I should have done this since I started -_- I'll take it into account from now on. Sounds like a good idea.

4) If permitted by your superior, fix faulty design aspects of the code. This only applies in certain circumstances such as where you are given the task to fix up a large, broken piece of software. As you start addressing design flaws, things quickly start to make more sense and perhaps you can come to understand the methods behind the madness.[/quote]
well, the game is already finished, so my changes won't have any effect, it's my local copy so I don't see the problem. I will start optimizing what I said before.


About what is good documentation and bad documentation... I've never written a big document (like what doxygen generates) but I have never been in a large project before either, so I guess I just have to get used to the way doxygen wants me to document stuff.
Anyways, about comments. In my opinion, when you create a class or function, there is a minimum of comments that it needs:
1. what is this class supposed to do (and what things isn't)
2. who is supposed to call it, and with what kind of parameters (nothing exhaustive)
3. maybe explain how it does it if it takes some unexpected approach to optimize it or something like that

for example, I'm finding stuff like
class command_text
as a class, and I have to go around figuring out what it does. But I would have done something like this

// this class prints text to the screen without any colors or anything
// it's supposed to be called on the menu screen, not inside the game
class command_text

(if I even use such a generic name for a class)

Share this post


Link to post
Share on other sites

[color="#1C2837"]About what is good documentation and bad documentation... I've never written a big document (like what doxygen generates) but I have never been in a large project before either, so I guess I just have to get used to the way doxygen wants me to document stuff.
Anyways, about comments. In my opinion, when you create a class or function, there is a minimum of comments that it needs:
1. what is this class supposed to do (and what things isn't)
2. who is supposed to call it, and with what kind of parameters (nothing exhaustive)
3. maybe explain how it does it if it takes some unexpected approach to optimize it or something like that


Good documentation (inline code comments) includes why something was written the way it is. I like seeing comments like:

// Don't remove this line because otherwise component X will crash (bugzilla-2152)


Good comments answer what when it isn't apparently obvious. E.g. the comment /* Use Newton-Raphson algorithm */ at the top of the function is all that I need to know and is an excellent comment. Another good comment:

long duration; // in msec


Bad comments (apart from obviously incorrect information) is how something was written and sometimes the what. For example:

i++; // increment i [BAD]
myDict = name; // place name into the dictionary [BAD]


I can determine that by looking at the code directly thanks.

Finally a good comment says the who.

// TODO: fixme [BAD]
// TODO-JS: fixme [GOOD]


With the second comment I know that my colleague John Smith is the one who I should put my hands around his throat... er go talk to.

Share this post


Link to post
Share on other sites
Be careful of making design changes though. Even if you make only a few simple ones, you'll need to perform tests to make sure they didn't break anything. That's the bad part (and why I only typically do design changes on already-broken software).


When I'm in charge of things, I prefer to document my code the following way:


1) Header files with heavy use of doxygen comments, documenting every class, method, member, function, and set of constants.
Example: http://allacrost.svn.sourceforge.net/viewvc/allacrost/trunk/game/src/modes/map/map_dialogue.h?revision=1888&view=markup

2) Source files with normal comments to quickly explain blocks of code, highlight important points, and insert TODO/TEMP comments appropriately.
Example: http://allacrost.svn.sourceforge.net/viewvc/allacrost/trunk/game/src/modes/map/map_dialogue.cpp?revision=1931&view=markup

3) External documentation for the software that gives a high-level architecture overview and the most common set of operations and interfaces someone would use
Example: http://allacrost.sourceforge.net/wiki/index.php/Quick_Start_Guide and http://allacrost.sourceforge.net/wiki/index.php/Scripting_Engine

4) Doxygen-generated documentation from the code to serve as a reference to the code (ideally automated to re-generate the documentation once a day or so)
Example: http://www.allacrost.org/public/doc/doxygen/index.html (note this is very, very outdated at the moment)


By the way, make sure you know what code standard your company is using as sometimes they include a standard for writing comments as well. And if your company doesn't have a code standard....uhhh, be worried. :unsure:

Share this post


Link to post
Share on other sites
I generally agree with loom_weaver on the descriptions of good/bad comments, though the 'in msec' comment is a bad comment. Well, not such a bad comment as 'duration' is a bad name. In general, I disagree with your assessment of comments:

1. what is this class supposed to do (and what things isn't)
[/quote]

This should be fairly obvious by name. And if you are good about your 'one class handles one task' it's even better.

Sure, sometimes things need to push the envelope or can't have a great name due to their... generalness. Then make a comment describing what's going on, but realize that the need to make a comment is a code smell.


2. who is supposed to call it, and with what kind of parameters (nothing exhaustive)
[/quote]

Protection level enforces who can call it, and your parameters have descriptive types/names to make the calling convention obvious.


3. maybe explain how it does it if it takes some unexpected approach to optimize it or something like that
[/quote]

Certainly. This is the case where comments are most valuable (in addition to loom_weaver's 'don't do this or else' or 'bug 4255 was caused by this being ___'). Cases where you divert from coding norms for a good reason. Comments exist to supply reasons to code, not to describe code.

Share this post


Link to post
Share on other sites
It sounds like the problem might be no clear module structure. Do the classes interact in a spaghetti fashion? Is there any attempt at separating subsystems into logical units?

Instead of looking at the code, try starting from a high level perspective and move down. So maybe figure out how a mouse click gets turned into an object action. Or try to figure out where from main() you get to some actual rendering. Find out what would be involved in adding a new game object. Do you have a full build environment? Play around with the code, actually change some stuff.

That might give you a better view of the "important" types and functions, the ones you are most likely to interact with when you go to work on extending this. You don't need to understand all the classes, there might be too many.

Share this post


Link to post
Share on other sites

Instead of looking at the code, try starting from a high level perspective and move down. So maybe figure out how a mouse click gets turned into an object action. Or try to figure out where from main() you get to some actual rendering. Find out what would be involved in adding a new game object. Do you have a full build environment? Play around with the code, actually change some stuff.


Yes an excellent idea! I forgot about the entire dynamic angle. Put a whole bunch of println statements in the code and then start executing some common pathways.

Resist the urge to write-off the codebase and disregard it as an a tangled spaghetti-code unholy mess written by incompetents. It may be indeed the case but in the real-world you need to work with legacy systems and that mind-set won't help you any.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

Participate in the game development conversation and more when you create an account on GameDev.net!

Sign me up!