Posted By: Anonymous
Real Programmers... - 04/01/10 08:53
"Real Programmers Don't Document - If it was hard to write, it should be hard to understand."
from the current Gamecreator Newsletter
from the current Gamecreator Newsletter
Real Programmers...
Posted By: alibaba
Re: Real Programmers... - 04/01/10 09:09
aannndd what should this mean...?
Posted By: Damocles_
Re: Real Programmers... - 04/01/10 09:13
the statement sounds stupit
Posted By: ello
Re: Real Programmers... - 04/01/10 09:16
haha, i am declared a real programmer. no, really i often think its a waste of time to document, but if i touch something half a year later, i hardly understand what i did there 
so i think its not too bad to put some comments in
so i think its not too bad to put some comments in
Posted By: Anonymous
Re: Real Programmers... - 04/01/10 10:15
Real programmers do understand this joke... 
Posted By: alibaba
Re: Real Programmers... - 04/01/10 10:21
aahh ok undertsood now
i have a game made 2 years ago and im still confused, what ive wrote there
i have a game made 2 years ago and im still confused, what ive wrote there
Posted By: Damocles_
Re: Real Programmers... - 04/01/10 11:12
The problem is, that most programmers actually DO not comment code.
Posted By: Anonymous
Re: Real Programmers... - 04/01/10 11:28
"The problem is, that most programmers actually DO not comment code."
...but they should - and that's the joke is for
[edit] programmers are often lazy people, they try to shrink the code to a minimum (so why waste lines for documentation *lol*)
...but they should - and that's the joke is for
[edit] programmers are often lazy people, they try to shrink the code to a minimum (so why waste lines for documentation *lol*)
Posted By: alibaba
Re: Real Programmers... - 04/01/10 12:00
..like mathematician
Posted By: Inestical
Re: Real Programmers... - 04/01/10 12:28
Real programmers don't backup nor comment their code. What you don't understand, you don't need to touch.
Posted By: William
Re: Real Programmers... - 04/01/10 20:58
Yeah, barely any of my code has comments on it. It makes it hard to go back to something a couple years back, but if you keep up with your knowledge, it all comes back within 5-10 minutes.
Posted By: Redeemer
Re: Real Programmers... - 04/03/10 23:04
The quote is a joke, Will. If you don't comment your code, others will have an impossible time understanding what it does. Also, it gets tiring trying to remember what significance FLAG2 has in your function after you've been absent from your code for a while.
Personally I've made it a habit to make a comment every time I do anything significant. If I turn on FLAG2, I make a comment. If I manipulate a vector with the "vec_" functions, I make a comment. Generally you should make comments that streamline the steps the computer should be going through in your function, such that if you read nothing but the comments in your function it should be clear what you're trying to accomplish.
Personally I've made it a habit to make a comment every time I do anything significant. If I turn on FLAG2, I make a comment. If I manipulate a vector with the "vec_" functions, I make a comment. Generally you should make comments that streamline the steps the computer should be going through in your function, such that if you read nothing but the comments in your function it should be clear what you're trying to accomplish.
Posted By: FBL
Re: Real Programmers... - 04/04/10 11:20
Guess I have mutated to an unreal programmer 
Posted By: HeelX
Re: Real Programmers... - 04/04/10 19:54
If you are a lone wolf it might be the case that you take less benefit from exhaustive commenting than if you work with others. What I have learned during programming for my bsc thesis, is that if you properly select the names of your variables, functions, methods, classes, interfaces etc.pp. you get your code very well self-documented. It doesn't mean that you should'nt do comments, though, of course... ;-)
Posted By: Captain_Kiyaku
Re: Real Programmers... - 04/04/10 20:04
Exactly what HeelX said, plus if you comment TOO many lines, your code will become unreadable. You can easily over see small lines of code (i=0; for example) and so on.
I just make comments when i get the feeling that i could forget what this code does. And i often give a comment line to every function/class i declare, just to be 100% sure what function it is.
I just make comments when i get the feeling that i could forget what this code does. And i often give a comment line to every function/class i declare, just to be 100% sure what function it is.
Posted By: Joozey
Re: Real Programmers... - 04/04/10 20:16
HeelX is right. The code should also speak for itself. Otherwise it is too complicatedly written. No need to comment what function PLAYER_GetName() does.
Posted By: MMike
Re: Real Programmers... - 04/04/10 20:35
i usually cooment, when i need //TODO , to add features toa function.. or
//Improve optimization
//or examplain, int a is a skill means "exame : area" send from the caller function...
or that sort of things..
//Improve optimization
//or examplain, int a is a skill means "exame : area" send from the caller function...
or that sort of things..
Posted By: FBL
Re: Real Programmers... - 04/04/10 21:13
Well the comments I do mainly are for auto generating documentation (I'm working on a template project).
All other comments are for my own understanding. I have coding guidelines, naming conventions and pick meaningful names, but still I explain some algorithms with comments because otherwise I would not understand anymore what I'm doing there.
All other comments are for my own understanding. I have coding guidelines, naming conventions and pick meaningful names, but still I explain some algorithms with comments because otherwise I would not understand anymore what I'm doing there.
Posted By: TWO
Re: Real Programmers... - 04/08/10 13:00
For people not commenting at all or having a 1:1 comment code ratio I would advice you to grab a good book. 'Clean code' for instance introduces nicely to self commenting code (like HeelX said) by naming things right.
Posted By: mpdeveloper_B
Re: Real Programmers... - 04/09/10 04:56
I agree with HeelX, I generally don't comment most of my code. I'm anal about the design of my code, I like to make it look pretty and it needs all of the indentions to be correct or else you can't tell where each thing begins and ends, but I also use variables and functions that are easy to read. I don't ALWAYS comment, but I might every once in a while.
Here's a random code example from Kino One:
You might not understand exactly what the code is for at first glance, but you do understand what it does. The code reads: "check the enemy's health, if the enemy's health is lower now than it was two frames ago, change the enemy's skin to his last one". At very first glance it doesn't look that way, but because of the name of the function and variables you can tell what the variables hold and what the function is supposed to do.
The code is used for flashing enemy models to their last skin which is a "white" skin used to achieve a "flashing" effect when an enemy is damaged.
My big problem is though, because of my lack of commenting a lot of times when you look at some functions you can't really tell what the variables are for, but I generally do that after working on a game for a while, and for prototyping, but when prototypes make it in the final game then the variables might be the same. It does make some things confusing, but for most global variables I TRY (don't always do) to make the variables understandable.
Here's a random code example from Kino One:
Code:
function skinchange()
{
var hp;
var newhp;
while(me)
{
newhp = my.health;
if (newhp < hp)
{
my.skin = ent_skins(me);
wait(1);
my.skin = 1;
}
hp = my.health;
wait(2);
}
}
You might not understand exactly what the code is for at first glance, but you do understand what it does. The code reads: "check the enemy's health, if the enemy's health is lower now than it was two frames ago, change the enemy's skin to his last one". At very first glance it doesn't look that way, but because of the name of the function and variables you can tell what the variables hold and what the function is supposed to do.
The code is used for flashing enemy models to their last skin which is a "white" skin used to achieve a "flashing" effect when an enemy is damaged.
My big problem is though, because of my lack of commenting a lot of times when you look at some functions you can't really tell what the variables are for, but I generally do that after working on a game for a while, and for prototyping, but when prototypes make it in the final game then the variables might be the same. It does make some things confusing, but for most global variables I TRY (don't always do) to make the variables understandable.
Posted By: FBL
Re: Real Programmers... - 04/09/10 06:27
I go even a step further.
Taking the code example above (not intended as criticism, only to have some work basis):
Why is it one time health, and then is it HP?
For me there is only one base name, and if I choose health for it, then my other variable would be var vOldHealth.
I would drop newHP completely, as it only reads the entity value one time and is used directly afterwards.
Also I would use a less generic function name, like checkSkinChangeOnHit().
Taking the code example above (not intended as criticism, only to have some work basis):
Why is it one time health, and then is it HP?
For me there is only one base name, and if I choose health for it, then my other variable would be var vOldHealth.
I would drop newHP completely, as it only reads the entity value one time and is used directly afterwards.
Also I would use a less generic function name, like checkSkinChangeOnHit().
Posted By: FBL
Re: Real Programmers... - 04/09/10 06:33
Okay, code striptease
An interface function of my state handler module.
The corresponding header file part looks like this:
The generated manual page:
http://firoball.de/stuff/toolbox_manual/state_8h.html#b420c531bd0c72348b153df19f7fd5b3
Code:
void STATEMGR_execute(STATEMGR* psState)
{
/* check whether atate machine is ready */
if ( (LIST_items(psState->psActions) > 0) && (LIST_items(psState->psTransitions) > 0) )
{
/* first check, if transition has to be done */
STATEMGR__checkTransitions(psState);
/* now execute cyclic action callback */
if (psState->pfAction != NULL)
{
STATEMGR__pfCallback = psState->pfAction;
STATEMGR__pfCallback();
}
}
}
An interface function of my state handler module.
The corresponding header file part looks like this:
Code:
/*! Execute cyclical actions and transition checks for State Machine. * Must be called cyclically. * \param psState Pointer to affected STATEMGR */ void STATEMGR_execute(STATEMGR* psState);
The generated manual page:
http://firoball.de/stuff/toolbox_manual/state_8h.html#b420c531bd0c72348b153df19f7fd5b3
Posted By: TWO
Re: Real Programmers... - 04/09/10 14:00
This is nice and ok in C. You provide doxy info how to use the function and in addition you comment scopes and important calls. In C++ function names would be much easier to read and as such the function wouldn't need this much inner commenting.
Edit:
Here a not-so-clean example of my code; Criticism welcome.
http://awake.svn.sourceforge.net/viewvc/awake/trunk/AwakeEngine/AwakeMain/include/AwEngine.h
http://awake.svn.sourceforge.net/viewvc/awake/trunk/AwakeEngine/AwakeMain/src/AwEngine.cpp
Edit:
Here a not-so-clean example of my code; Criticism welcome.
http://awake.svn.sourceforge.net/viewvc/awake/trunk/AwakeEngine/AwakeMain/include/AwEngine.h
http://awake.svn.sourceforge.net/viewvc/awake/trunk/AwakeEngine/AwakeMain/src/AwEngine.cpp
Posted By: mpdeveloper_B
Re: Real Programmers... - 04/10/10 17:06
I also use prefabs, I used to not do them, but when I learned how much of a time saver they were I started doing them. Generally If I would give that out to the public, I would do what you did, give a readme.
Of course, this still proves I don't comment alot lol
I'm a butt-end of the joke.
Of course, this still proves I don't comment alot lol
I'm a butt-end of the joke.