Orca C++ Programming Style Guide

Note:: Reviewed for release 2.14.0.

This is a guide to programming style used within the Orca framework. Main reason for its existence: to maintain a legible and uniform code-base.

Main inspiration came from two modern well-designed C++ frameworks: Qt and Ice.

Table of Contents

Variables

Variable names begin with low-case letter and each next word is capitalized.

int    x;
my_t   myVariable;

No "Hungarian" notation, e.g. a float variable should be width and not fWidth.

Functions

Function begin with low case letters, each next word is capitalized. This is the same rule as normal variables, but member function names are followed by parameter lists "(..)".

void convert( ... );
std::string toString( ... );

Classes and Structures

Class and structure names begin with a capital, and each new word begins with a capital (no "_" or "-").

class     MyClass;
struct    MyStruct;

No "Hungarian" notation, e.g. we do not use CMyClass.

Member Variables

Same as normal variables but appended by "_". This makes code clearer, letting you know instantly where to look for variable definition.

private:
    int      x_;
    MyStruct myVariable_;

Member Functions

Same format as normal functions.

public:
    std::string toString();

A common class of member functions are access and assignment functions which serve as public interface to private member variables. Access functions have the name of the member variable which they provide access to (without "_"). They are typically have a const modifier. Assignment functions preperd "set" to the variable name.

public:
    int    x() const        { return x_; };
    void   setX( int x )    { x_ = x; };
private:
    int    x_;

Namespaces

All low case. Easily destinguished from functions and variables two by "::". Keeping namespace names reasonably short makes code more readable.

namespace myspace
{
    void myFunction();
}
...
// function in namespace
myspace::myFunction();

// compare to a class member function
MyClass::myFunction();
...

As a general rule, do not place "using" directives in header files. They propogate down into every source (.cpp) file that includes your headers, whether or not the calling programmer wanted to import the entire namespace (e.g. std). Some projects may have their own classes called map, or string, or list and a single "using" statement deep inside nested header files can cause unanticipated namespace collisions.

In general, it's safest and most polite to refer to classes canonically in header files (std::string, etc), and keep the "using" statements in your implementation files.

Enums

The name of the enum and each element has format of a class: begin with a capital and each new word begins with a capital.

enum MyColor
{
    Red,
    Blue,
    DarkBlue
};

#defines

All uppercase to distinguish them from functions and variables.

#define VERY_BIG_NUMBER 5

Special case are header file defines (to prevent multiple loading). Make sure that the string will remain unique if the header file is used in a different project. Prepend project name or other distinguishing feature. Eg.

#ifndef MYLIB_POINT_H
#define MYLIB_POINT_H

File Names

All low case for ease of porting to non-Unix file systems. Underscores ("_") are generally not used. To keep the Unix systems happy, no spaces in file names are allowed.

File extentions:

C/C++ header files: h
C++ source files: cpp
C source files: c

A name of the file defining a class is typically the same as the class name with adjusted capitalization.

main.cpp myclass.h myclass.cpp
device.h device.cpp

File names of libraries have each word capitalized. The word Orca is prepended to the start to make it clear where this library came from.

libOrcaMyLibrary.so
libOrcaMyLibrary.a

CMake file formatting

All standard CMake functions are low-case. All custom macros are upper-case. Custom macros should start with the name of the project where they are defined.

Variables defined and intended to be used within a single directory (pseudo local variables) are low-case. Variables intended to be used in child directories and in the cache (pseudo global variables) are upper-case.

set( build TRUE )
GBX_REQUIRE_OPTION( build EXE ${APP_NAME} ON )