#152941 - strat - Sun Mar 23, 2008 2:33 am
I just got my GBA game to detect collisions between the sprite and the background, by checking the difference between the midpoints of the sprite bounding box and the background metatile. When a sprite overlaps the metatile, it's sent back an equal amount that it moved into the solid space.
Now here's the dumb part...figuring the sprites would change speed at some point (but not caring at the moment, since getting the collision itself to work drove me nuts), I used a for loop to call the code to send the sprite back. The terminating condition? The difference between the midpoints. Problem is, the same subroutines are used to move the sprite normally and move it out of the solid space. The result was a bouncing screen and me taking awhile to remember those for loops even existed.
It's becoming clear that 40% of my coding time will be productive and the rest will be finding silly mistakes like this. So I'm wondering how any of you document your coding? Right now I'm just using some totally English pseudo-code.
I'm not willing to use flow charts, but a function and variable database might be an idea. Like, trace a local or global var through all the functions its passed to and what's done with it. I'm thinking about making an ODBC app for it.
Oh, and if this is already a topic, uh, now you really know why documenting is necessary.
#152965 - Quirky - Sun Mar 23, 2008 2:06 pm
Don't bother writing an app - somebody has probably done something already. What you mention sounds a lot like what Doxygen can do for you. By clicking links you see where your variables are passed to. Ctags and Vim - press g] on a function call - gives a similar navigation approach.
I tend not to write (or read for that matter) many source code comments. They are usually noise, "set variable x to 3", or just outright "lies" - comments that lost their meaning after changes in the code. Psuedo code is a good idea for your important algorithms. Easier to read the overview than dig in, but only if kept up to date.
#153119 - strat - Tue Mar 25, 2008 6:06 am
I might check out Doxygen. For comments I usually summarize what a chunk of code is doing and maybe give the purpose of variables.
#153171 - tepples - Wed Mar 26, 2008 12:04 am
Java recommends a standard "javadoc" format for comments before each function, and doxygen can parse it in other C-like languages.
| Code: |
/**
* Counts the bits in a bit vector that are true (1).
* @param b a bit vector
* @return the number of 1 bits
*/
unsigned int countOnes(LJBits b) {
unsigned int ones = 0;
while(b) {
++ones;
b &= b - 1;
}
return ones;
} |
_________________
-- Where is he?
-- Who?
-- You know, the human.
-- I think he moved to Tilwick.
#153178 - Lord Graga - Wed Mar 26, 2008 1:45 am
Heh, that's a pretty elegant algorithm, tepples.
#153786 - sgeos - Sun Apr 06, 2008 7:57 am
I follow the religion of self documenting code. Comments are few and far between, and generally look like code. I also believe that both method/function parameters and should be identifiable at a glance, and parameters should be treated as read only.
| Code: |
BOOLEAN is_alive(critter_t pCritter)
{
if (0 < pCritter.hp)
return FALSE;
// else
return TRUE;
}
id_t next_id(id_t pId)
{
id_t id = pId + 1;
if (id < gMaxId)
return id;
# else
return correct_id(id);
} |
If code is not self documenting, it should be documented. ...OK, I'll actually argue that it should probably be refactored. =P
As for tepples's code? A good example of non-self documenting code that should be documented but not refactored. "b &= b - 1" is non-obvious.
-Brendan
#153788 - SevenString - Sun Apr 06, 2008 9:18 am
All my classes, variables, methods, etc. tend to be very descriptive. Heck, I often even name indices with specific verbose names, such as "conceptBindingArrayIndex".
If there's anything truly complex and non-intuitive going on (which is OFTEN in my latest system), I document the crap out of it, both in-line and externally.
I've built up quite a collection of architectural diagrams, white papers, API documentation, etc.
If I'm making some DS homebrew? I do more explicit documentation of my asset pipeline than I do of my code.
Mainly because I hate coming back to fix some graphic asset, only to have forgotten half the steps that it took to get it into the game. "Now WHAT tool was I using to merge those palettes?" lol
My latest homebrew is mixing several iso backgrounds with transparency, a complex collision map system, and some 3D layering and animation. If I didn't have a documented process, I'd be totally lost.
_________________
"Artificial Intelligence is no match for natural stupidity."
#153869 - gauauu - Mon Apr 07, 2008 5:07 pm
| SevenString wrote: |
Mainly because I hate coming back to fix some graphic asset, only to have forgotten half the steps that it took to get it into the game. |
Do you not use makefiles and scripts to automatically convert from the original asset source into the game format? Or do you mean in addition to this?
#153871 - SevenString - Mon Apr 07, 2008 5:48 pm
| gauauu wrote: |
| SevenString wrote: |
Mainly because I hate coming back to fix some graphic asset, only to have forgotten half the steps that it took to get it into the game. |
Do you not use makefiles and scripts to automatically convert from the original asset source into the game format? Or do you mean in addition to this? |
In addition to make and batch files.
I'm talking more about the design and documentation of the overall art/asset pipeline, beyond the usual "sprites over a scrolling background" kind of thing.
_________________
"Artificial Intelligence is no match for natural stupidity."
#154082 - Jinroh - Thu Apr 10, 2008 6:45 pm
I use a method of both self-documenting and pseudo-code comments.
It may be overkill, but some of my older projects, like from High School I go back and try to read some of what I was doing and I'm just baffled by the non-use of whitespace and comments. It's atrocious.
Anyway, I'm the type of person who if they go back to a project after a coma want to understand it and be able to pickup right away. Or Amnesia even. :D
_________________
The lone Wolf howls, driven by pride he presses on. Knowing not where he goes, but only where he wants to be.
~Me~
#154119 - naleksiev - Fri Apr 11, 2008 4:23 pm
I think if the code needs comments to be understood than it's written bad. Of course some optimized algorithms or important code could benefit from 2,3 lines explanation.
#154154 - sgeos - Sat Apr 12, 2008 12:49 am
| naleksiev wrote: |
| I think if the code needs comments to be understood than it's written bad. Of course some optimized algorithms or important code could benefit from 2,3 lines explanation. |
I could see this as a rule of thumb, but there are times when comments are needed. Sometimes your task is just odd, so the code comes out odd. In that case it should be documented.
I find that I sometimes put links to documentation in my code. If, for example I searched for flood fill algorithms when writing the module, I might note the sites I used.
-Brendan
#167234 - keldon - Fri Mar 06, 2009 6:02 pm
Maybe try commenting your code like you are writing a tutorial, the aim is to explain what and why when needed.
#169637 - Karatorian - Mon Jul 27, 2009 6:00 pm
| SevenString wrote: |
If I'm making some DS homebrew? I do more explicit documentation of my asset pipeline than I do of my code.
Mainly because I hate coming back to fix some graphic asset, only to have forgotten half the steps that it took to get it into the game. "Now WHAT tool was I using to merge those palettes?" |
Hmm, that's about the exact opposite of me. My asset pipeline is code (make files and python scripts mostly).
#169659 - elwing - Tue Jul 28, 2009 8:02 am
you should definatly use doxygen, it is simply great... and if it does not suit your own needs you can even pre process your code for documentation using custom perl scripts...