Code Conventions

[Ch1156]

I am improving my C++ and I decided to start using conventions to make my code more readable and fluent, I came up with this list, it's not done yet but tell me what you think, is there anything I can add or change?

C++ NAMING CONVENTIONS
Version 1.0

FUNCTIONS

Every word in a function name must begin with a capitol letter. Functions should be as small as possible, this helps readability and helps making error finding easier. There is no set verticle length however including GUI and Graphics API code functions shouls not exceed 120 lines. Functions also must not contain "_" characters in the name.


Bad Example:

void functionOne();
void function_One();


Good Example:

void FunctionOne();


If a functions parameter list is longer than three items, then wrap the parameter list.


CLASSES

Like function names, all words in a class name must begin with a capitol letter.
All data members in a class must be private, and accessed through accessor functions.


INITIALIZATION

When declaring a variable, whether it be local or not, always initialize variable with
something unless it will cause application errors when running.


Bad Example:

int i;
i = 23;

Good Example:

int i = 23;


LOCAL VARIABLES

Prepend local variables with loc_.

Example:

unsigned short int loc_enter_choice = 0;


FUNCTION ARGUMENTS

Prepend function arguments with arg_.

Example:

void Function(unsigned short int arg_player_health, const string arg_player_name):


DECLARING VARIABLES

When declaring variables anywhere in code, always place them at the top of the function and organize them based on type, separating each category with a space. If variables have more than one word in them, they should be separated by an underscore. All variable names should be lower case.

Bad Example:

vector<string> vecVectorThree;
int intOne = 0;
int intTwo = 9;
vector<int> vecVectorTwo;
string strOne = "";
float floatOne = 0.0;
int intThree = 7;
vector<int> vecVectorOne;
vector<float> vecVectorFour;


Good Example:

int int_one = 0;
int int_two = 9;
int int_three = 7;

string strOne = "";

float float_one = 0.0;

vector<int> vec_vector_one;
vector<int> vec_vector_two;
vector<string> vec_vector_three;
vector<float> vec_vector_four;

Note: Vectors have types within their bracers, do not put a space between them even if there are different types, just organize them together. Type order does not matter.


POINTERS AND REFERENCES

When declaring pointers and references, place the declaration next to the variable name.

unsigned short int player_health = 100;
unsigned short int *int_one = &player_health;




PROTOTYPES

All prototypes that are not part of a class must go into a .h file name "Prototypes.h".
Functions should be organized by name in alphabetical order. Although function prototypes inside classes should be organized alphabetically as well.


NAMING

Variable names should not be abbreviated, the name should be as descriptive as possible within reason. When looking at a variable or function name, you should know just by looking at it what its purpose is.


COMMENTS

Always place comments in code for functions and code chunks. Comments can be as long as needed to explain a function or chunk, however it should be kept as short as possible.

Use // only for writing comments and /* */ for commenting out code, even if the code is one line, always use /* */ for code.

Use //TODO for code that needs to be written, //FIX for code that needs to be fixed, //BUG //END BUG for code that is known or thought to cause a bug, put //BUG before the code and //BUG END after so it is known what line or chunk is causing problems.


LINE LENGTH

Line length should not be longer than half the width of the editing area.

[LB]

Ch1156 wrote:

Every word in a function name must begin with a capitol letter.

Does it matter which country I choose the capitols from?

Ch1156 wrote:

Functions should be as small as possible, this helps readability and helps making error finding easier.

Good.

Ch1156 wrote:

There is no set verticle length however including GUI and Graphics API code functions shouls not exceed 120 lines.

Exceeding 50 lines should be cause for alarm.

Ch1156 wrote:

Like function names, all words in a class name must begin with a capitol letter.

Generally class names and function names have different naming conventions to at-a-glance tell them apart, but it's not very important and this is your personal preference.

Ch1156 wrote:

All data members in a class must be private, and accessed through accessor functions.[quote]I summon @Disch to give a briefing.[quote=Ch1156]When declaring a variable, whether it be local or not, always initialize variable with
something unless it will cause application errors when running.

Don't neglect to mention constructor initializer lists and defaulting the initialization of member variables in class scope.

Ch1156 wrote:

Prepend local variables with loc_.

That's an interesting one, most people leave local variables untouched and do weird things to their member variables. This is a personal preference though.

Ch1156 wrote:

Prepend function arguments with arg_.

Ditto.

Ch1156 wrote:

When declaring variables anywhere in code, always place them at the top of the function and organize them based on type, separating each category with a space. If variables have more than one word in them, they should be separated by an underscore. All variable names should be lower case.

This is nonsensical. You should declare variables as you need them, not upfront. It may not even be possible to organize them based on type given your rule to always initialize variables with a value immediately.

Ch1156 wrote:

When declaring pointers and references, place the declaration next to the variable name.

I like to call this "snuggling". You and I both prefer to snuggle with the identifier instead of the type, though generally in C++ it makes more sense to snuggle with the type. Again, personal preference.

Ch1156 wrote:

All prototypes that are not part of a class must go into a .h file name "Prototypes.h".

Throwing organization out of the window to favor a "put miscellaneous things here" approach?

Ch1156 wrote:

Functions should be organized by name in alphabetical order. Although function prototypes inside classes should be organized alphabetically as well.

Just let your documentation generation tool do that for you - organize the code by what logically makes sense. Alphabetical order is a side effect of using a written language to name your functions.

Ch1156 wrote:

Variable names should not be abbreviated, the name should be as descriptive as possible within reason. When looking at a variable or function name, you should know just by looking at it what its purpose is.

The best laid plans of mice and men.

Ch1156 wrote:

Always place comments in code for functions and code chunks. Comments can be as long as needed to explain a function or chunk, however it should be kept as short as possible.

Don't neglect to mention documentation comments. You should choose a documentation generation tool (e.g. Doxygen).

Ch1156 wrote:

Use // only for writing comments and /* */ for commenting out code, even if the code is one line, always use /* */ for code.

Generally, you should do the opposite due to how /**/ works (it does not support nesting). This has been well discussed before, do some Googling ;)

Ch1156 wrote:

Use //TODO for code that needs to be written, //FIX for code that needs to be fixed, //BUG //END BUG for code that is known or thought to cause a bug, put //BUG before the code and //BUG END after so it is known what line or chunk is causing problems.

I suppose if you're in a rush to get things working you might initially write buggy code, but what generally happens is that it doesn't get repaired until it actually breaks.

Ch1156 wrote:

Line length should not be longer than half the width of the editing area.

This is ambiguous - who's editing area? On what day of the week? Thundsday?

[squished18]

Instead of re-inventing the wheel, it might be advisable to use an established convention:

http://google-styleguide.googlecode.com/svn/trunk/cppguide.html

[dhayden]

I came up with this list

Be careful. In my experience, when people come up with a list or a process or a convention, it quickly becomes more important than the code itself. That's because it's easier to fuss over the convention. What really matters is that you write clear, correct code. The way you name your variables is secondary. Also, when there are many people involved, stuff like this turns into a holy war.

I wrote a document on coding conventions at work because our off-shore developers were asking for it. There are only two "required" conventions: (1) put the copyright notice in every file and (2) comment your code. The document addresses many of the other things you've mentioned, but more from a "this is why you might want to do something like this" standpoint.

Prepend local variables with loc_.
Prepend function arguments with arg_.

I don't think this is necessary. It's common to prefix class members, but the local vars and args are declared right near the usage, so why prefix them?

All data members in a class must be private, and accessed through accessor functions.

Why stop at data members? Why not make all variables accessible only through accessor functions....? Don't blindly use accessors. They get in the way and frequently aren't needed. You should evaluate each case to decide if an accessor is warranted.

always place [variables] at the top of the function

As LB pointed out, it's common to put them as close to their use as possible. To me this is a judgement call. The advantage of putting them at the top is that you know where to look to find the declaration. If they are declared as needed, then they will likely be right on screen and you'll save on stack space (when a variable goes out of scope in a code block, its memory becomes available for a new var.

But I think the overriding concern here is the time required to construct/destroy the variable. Consider

MyClass x;  // MyClass constructor takes a long time
for (int i=0; i < 1000000; ++i) {
    x.doSomething();
}

vs.

for (int i=0; i < 1000000; ++i) {
    MyClass x;  // MyClass constructor takes a long time
    x.doSomething();
}

The second example will run much slower because x is constructed and destroyed a million times instead of just once. True, the meaning is different and you may need to construct a new x each time, but if you don't it would be a shame to waste the time.

All prototypes that are not part of a class must go into a .h file name "Prototypes.h".

This seems arbitrary. It will be handy to have miscellaneous prototypes in a common place, but frequently you want or need different header files.

Variable names should not be abbreviated, the name should be as descriptive as possible within reason. When looking at a variable or function name, you should know just by looking at it what its purpose is.

I prefer short names and comments at the declaration to say what they are. That way the code is short and clean but you can still tell what a variable really is.

COMMENTS

In my opinion, what you put in your comments is far more important than all the other stuff you've mentioned.

Comment the declaration of each non-trivial function and method, describing the parameters, functionality, return value and error conditions. I like to put the same comment in both the declaration and definition. At the declaration you want to say what the function does, but probably not how it does it. Leave that for the definition.

Comments in the code should say how and why you're doing something. The code itself usually says what you're doing, but you might want to add brief descriptions before each block of code. Sometimes I'll write a description of the steps that the code must perform, put that into comments, and then write the actual code around these comments.

Line length should not be longer than half the width of the editing area.

As your manager I see that the right side of your screen is always blank, so I'm giving you a monitor that's half as wide.... :) Seriously though, I don't see the reasoning here. To me, you don't want code lines that wrap around the edit window. Also, if the code is indented 17 levels, then it's a pretty good sign that you need to change something.

Re-reading this post, I see that all of the above comments are critical. I want to say that it's a very good thing to think about these issues and come up with some sort of conventions. Much of what you've written is quite reasonable and a good idea.

[maeriden]

Instead of re-inventing the wheel, it might be advisable to use an established convention:

http://google-styleguide.googlecode.com/svn/trunk/cppguide.html

http://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Exceptions
Bah.

[keskiverto]

http://www.gotw.ca/publications/c++cs.htm

There are even more conventions out there.

[MiiNiPaa]

http://xkcd.com/927/

Use coding standard team you belong to uses.
Aside from that you can do everything you want. There is standards of different level of ridiculousness (Google, I am looking at you).

I personally prefer C++ standard-like functions naming, pointer/reference position, and modified K&R formatting style.

[Cubbi]

It's hard to find a guide worse than Google's (the exception ban is only a tip of the iceberg)

[LB]

What's so wrong with the exception ban?

[Cubbi]

It turns C++ into a fundamentally different language, one without RAII or guaranteed class invariants. I posted a list of this and other google guidelines that I find unacceptable at https://www.linkedin.com/today/post/article/20140503193653-3046051-why-google-style-guide-for-c-is-a-deal-breaker

[LB]

Split discussion into new thread:
http://www.cplusplus.com/forum/lounge/142618/

By the way, I agree with the rest of your points in that article.

[Ch1156]

Thank you all for your suggestions i will revise my document using them.