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.
Reading someone's code
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.
Author
[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
I've been told to read and understand the code, but there is barely any comments on it.
Welcome to the real world! It sucks here.
Seriously though, you'll have this problem in software development no matter how experienced you are and at most companies as well. I've been developing software for a good decade, including graduate thesis work, professional engineering careers, and open source projects in my spare time. Almost always, the code is very poorly documented, and may be poorly designed as well. No matter how good you are as a programmer, if the design is a bunch of spaghetti code thrown together with no explanation, you're going to have a difficult time learning what someone else spent months or years doing.
So what can you do? Not much, unfortunately. These are the steps that I typically take when I encounter the same problem you are (which is depressingly too often).
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.
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.
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.
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.
In general, try to go about looking through the code in a way that makes sense. Maybe you start at the program's main function (if its an application) and follow the overall flow of where the code does and how it operates. Or maybe you take a higher approach and start looking through one component of the code base at a time (if you're lucky enough that components are well compartmentalized). There is no single "best approach" to learning unfamiliar/undocumented software. It depends on the type of software the code creates and what learning abilities are most effective for you. Typically, I like to take a mix of bottom-up and top-down approaches, looking at how the application starts up and the highest levels of classes and their relation to one another, before I go diving into the smaller classes and implementation details.
There are a lot of really bad programmers out there who should either take the initiative to learn and apply proper software design and practices, or find a new career that they don't suck so much at. Unfortunately, these people make our lives hell, and have generally made me extremely cynical and discontented with "professional" software development. (I actually quit a contract I was hired for last summer after only two weeks over my frustrations with it; I was handed a 10 year old code base with zero documentation and zero explanation about it from anyone). And most importantly, don't contribute to the shit pile of bad code in the world. Make sure that the code you write is well designed and documented for those that follow.
Author
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 startedI'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)
[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.
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.
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.
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.
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.
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.
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.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
