Found at: http://publish.ez.no/article/articleprint/35/

Coding Standards - Part 3 - What remains

Publishing date: 29.11.2000 18:08

In the third and final issue we'll dig into the details regarding naming conventions, functions, name spaces, classes, comments and exceptions.

Naming conventions

All names must be written in English, and be grammatically correct. Avoid names that don't mean anything, like foo and tmp. Any numbers in a name must be written using letters, not numbers, unless there is a good reason not to.

ValueOne

Functions can be made up from several words, the first letter of each word in uppercase and the rest in lowercase. The first word must be all lowercase. Acronyms should not be used.

void setText( const QString &text );

Constants are written in uppercase, multiple words divided by underscore.

const float PI = 3.1415;
const int MAGIC_NUMBER = 42;

Enumerators and member variables can be made up from several words, the first letter of each word in uppercase and the rest in lowercase. They should normally not consist of more than three words. Acronyms can be used as long as the meaning is obvious.

enum DayType
    {
    Monday,
    Tuesday,
    ...
    };

private:
    int Len;
    int X,Y;

Local variables can consist of several words, using only lowercase. Use underscore to divide words. Use as few words as possible, and use acronyms when needed. Special acronyms like i (index) and x,y (position) are allowed. Parameters should be named in the same way as local variables.

int i, index, x, y;
int x_add;

Class names can be made up from several words, the first letter of each word in uppercase and the rest in lowercase. All classes made by eZ systems should begin with eZ.

class eZDialog;
class eZModuleManager;

Static variables should be named like member variables, but they must end with an underscore.

static int RefCount;

Never use global variables, put them in a class and make them static.

Functions

All functions must be placed inside classes. Exceptions are main() and functions used as an interface between classes and a C API. Functions should be short and do one task. The length of the function depends on how complex it is. The more complex the function is, the shorter it should be. Too long functions should be split into several functions each doing a minor task. A function should not be longer than 30-40 lines.

Use variables sparingly, split the function when you have too many. If the function is clearly divided into different parts you may use more variables, but no more than 7 per block of code. Exceptions to this rule are certain mathematical calculations where speed is essential.

If a function has many parameters it might be wise to split the parameter line into several lines, place the parameters with a close relation to each other on the same line. Many parameters is often a sign that your function is too big, try splitting it.

Try to make functions const as often as possible. Avoid inline code, but when you do use it, try to post phone it until the class is considered done. This is to avoid massive recompiling due to dependencies. Be careful with default values for function parameters, try to specify everything as explicitly as possible.

Name spaces

In order to avoid bad or too long class names, use name spaces to split and ground classes and functions. This means that two classes can have the same name as long as they exist in different name spaces, enabling you the use more intuitive names. However, before you start using name spaces make sure it will work on all platforms used in the project.

Classes

Classes should do only one thing and do it well. Split it into subclasses if it's too big. Use multiple inheritance sparingly, consider using a pointer to an object (this is often called composition) instead of inheriting it.

All member variables must be private. When access to member variables is required use functions, never use public or protected variables.

Helper functions should be private. Functions that don't access member variables or functions can be made static.

Comments

For every function, write a comment that explain what it does, and any hard-to-understand parameters. These comments should be written in Doxygen syntax. Also write a comment on a class' area of responsibility. Use a newline between comments and functions.

Don't over comment your code, use comments when needed. If you have to put lots of comments in your code to make it readable, it's a sign that it is badly written and should be redone.

Exceptions

Use exceptions to control things that don't work as they were expected to, like parameters having values they should never have. Use them often. Don't use exceptions as a way of leaving loops or nested function calls, or signalling an expected outcome. Be aware of memory leaks that may happen when using exceptions. (The book "The C++ Programming Language" by Bjarne Stroustrup has comments on this.)

Functions that use exceptions should explicitly state so in the documentation. When using a function with exceptions, always use a try/catch statement to handle it. Use a try/catch statement in main() to tell the user/developer of any fatal errors that happens.

That's all, folks!

Now you've seen the C++ code standard for eZ systems as. If you like it, use it, if you don't, write your own or consider using on of the existing ones on the web. If you only write your own code and never share it with others you might not need too explicitly write a standard, in most other cases it would greatly benefit the consistency and readability of your project.

| Back to normal page view |