Quote:
Here's a friendly piece of advice: your excessive commenting will waste lots of your time. Look around for some articles and hints about writing "good" comments.

Indeed, for example:


should be done without magic values, no matter how well they are commented:



Now you can either remember the name of a particular game state (rather than trying to memorize magic values), or you can easily look it up in the enum. Also there's no possibility of a "comment going out of synch with the reality".

Why would you initialize an "extern int"? Why don't you initialize it in the module that defines it?

@Codeka: As I said, I'm aware of that - but it works just fine for what I'm using it for, which is why I asked that comments like that be kept to yourself.

@Windryder: I'm aware of the 'problem' of over-commenting, and I do agree that my code is over-commented, but only slightly. In all honesty, I prefer it that way for 2 reasons. One, should I ever decide to release the full source for other people to work on, extra comments come in handy. Secondly, and more importantly, it works better for me. I code as a hobby....in my spare-time. I'm busy quite often, so while some days I can spend a good 4 hours writing code, other days I only write a few lines or notes before bed. Sometimes I go weeks between chances to work on a hobby project. So being able to immediately know what every group of code does also helps me find which part of the project I am trying to modify/add to, etc. So remember...over-commenting is different depending on the situation and coder.

@ApochPiQ: Sorry, won't happen again.

@Sneftel: The intention wasn't to make it '1337'. Only certain comments are structured like that...the ones that mark sections of the code. I made them like that so that they'd stand out compared to other comments (which is why they are all in caps and underlined). It helps me find certain sections of my code that I intend to be adding more to as I progress.

@Visitor: The 'magic values' as you put it are just as easy to remember in my opinion and just as easy to look-up as the comment is at the top of my main.cpp. Though I will thank you for the 'enum' tip. I don't program in C/C++ very often but have been trying to change that. I didn't know about enum...and I will probably change that portion of the code to use that. As far as out-of-sync problems go....non-existent as I already thought of that and if game_state goes out of bounds it cleanly exits the program....which at this point adds convenience as not all game_state's are coded yet.

@alvaro: That was a mistake....I changed the way the program was written which involved making that an extern variable. It was originally declared and initialized at the same time as a local variable and I simply copied it and added "extern" before it. I'm pretty sure the compiler stopped on that after I fixed my original comment problem, as I'm pretty sure declaring and initializing an extern variable isn't allowed. It is now initialized in main() as it should be. :)

Quote:@Visitor: The 'magic values' as you put it are just as easy to remember in my opinion and just as easy to look-up as the comment is at the top of my main.cpp. Though I will thank you for the 'enum' tip. I don't program in C/C++ very often but have been trying to change that. I didn't know about enum...and I will probably change that portion of the code to use that. As far as out-of-sync problems go....non-existent as I already thought of that and if game_state goes out of bounds it cleanly exits the program....which at this point adds convenience as not all game_state's are coded yet.

A good principle with comments is: prefer self-commenting code to comments. The enum approach clearly helps you write self-commenting code, because the names you give to them already describes their meaning.

It also helps in places where you use it. E.g perhaps a state change right now looks like this:

//switch into new gamegame_state = 1;

Now, suppose, you want change this place, so that you don't switch to new game, but some state inbetween:

//switch into new gamegame_state = 17;

It is so easy to forget to update comments, and if that happens, the comments only serve to confuse yourself and anyone else reading your code.

Compare with:

game_state = new_game;

changed into

game_state = preparing_for_new_game;

Now there's no point in commenting what that statement is doing, because that is obvious, but you might add a note why you are switching to preparing_for_new_game and not directly to new_game.

Sorry if I came off defensive, I didn't mean to. I was just justifying why my code / comments were structured the way they were. I honestly am greatful for all the replies. I'm not embarassed that I learned something new though. I mean....that is why I came here in the first place. I knew something was wrong, couldn't figure it out myself and came here.

So yeah I have learned a few new things....Don't end any line with "\" or many other characters that mean something to the pre-processor; I've learned the use of enum...and am currently implementing that into my project as I optimize the efficiency of some of my functions; I've learned not to mark anything as "Solved" in this forum; And that even if you tell someone not to make a remark about something....someone will. :P

Anyway I would like to thank everyone for their input and apologize for coming off as extremely defensive.