Conventions

Some coding conventions I prefer.

White Space

Let indentation improve readability whenever possible. Only use blank lines between two lines of equal indentation. This gets more lines on the screen at once to improve overview of current code segment.

So this:

 void Player::Update(double _dt){  
   
   // step the current state (states do all the work)  
   current_state->OnStep(_dt);  
   
   // helper to update the position  
   update_position(_dt);  
   
   // check for state change  
   if (current_state->StateOver()) {  
   
     current_state->ChangeToNextState();  
   }  
 }  

becomes:

 void Player::Update(double _dt){  
   // step the current state (states do all the work)  
   current_state->OnStep(_dt);  
   
   // helper to update the position  
   update_position(_dt);  
   
   // check for state change  
   if (current_state->StateOver()) {  
     current_state->ChangeToNextState();  
   }  
 }  

Bracket Style

I used to always prefer this style for readability:

 void Class::Method()  
 {  
   // do stuff  
 }  

But after getting used to it, it's really no more readable than:

 void Class::Method(){  
   // do stuff  
 }  

Prefer this style for the same reason as above - more lines fit in the same vertical space, giving a better overview of the current code segment.

Also, always use brackets, even when optional! For example, don't do this:

 while(condition)  
  do_something();  
   
 do_something_else();  

It just makes it a pain when the code develops and you want to change the loop to contain more than one line. It is especially annoying in nested blocks.

Parameter Names

This is the only time I ever use an underscore prefix. It helps not only to avoid member variable name clashes, but makes it clearer within the method when you are working with a passed in parameter, and when you are working with a member.

Method Names

For public methods, use camel case.

For private functions, use all lower case with underscore between words.

I think this differentiates nicely between the actual interface of the class, and private functional/procedural-style helpers to encapsulate private functionality.

It's kind of like, when you talk in public you try to speak well with proper grammar (camel case for the public interface: it kind of looks official and formal) but when you're chatting in private, it's less formal (lower case, underscore style). That's how my brain sees it, at least!

Comments

Although useless comments can help make the code look prettier, they just add unnecessary vertical bulk. High level languages document themselves with good class and method names. Let the code speak for itself wherever possible.

For example, none of the comments in this snippet are necessary, they should be removed!

 void Player::SetPosition(int _x, int _y){  
   // set the players x position  
   position.x = _x;  
   
   // set the player y position  
   position.y = _y;  
   
   // update the sprite position  
   sprite->SetPosition(position.x - sprite->GetWidth() / 2, position.y - sprite->GetHeight());  
 }  

Method Documentation

Use Doxygen documentation in header files. In source files I like the following comment block, I think it helps segregate functions and makes files with lots of methods easier on the eye. In this case, I think it's worth the sacrifice of vertical space. Though, as with all of these conventions, I'm open to persuasion!

 // --------------------------------------------------  
 // SetPosition  
 // --------------------------------------------------  
 void Player::SetPosition(int _x, int _y){  
   position.x = _x;  
   position.y = _y;  
   
   sprite->SetPosition(position.x - sprite->getWidth() / 2, position.y - sprite->getHeight());  
 }  
   
 // --------------------------------------------------  
 // AttachInput  
 // --------------------------------------------------  
 void Player::AttachInput(GameLib::Input::InputDevice* _input){  
   input = _input;  
 }  
   
 // --------------------------------------------------  
 // DetatchInput  
 // --------------------------------------------------  
 void Player::DetatchInput(void){  
   input = NULL;  
   ResetVelocity();  
 }  

Tabs vs Spaces 

Prompted by a reply on google plus, my view on this controversial one is that you should use tabs for indentation. That's what a tab is for, after all. Plus, it allows people to customize thier indentation size when reading your code, without modifying the file.