TagAdA

TagAdA Coding Style Guidelines

You will find here some of the guidelines we try to stick to when writing code for TagAdA.

We comply with the vast majority of Geotechnical Software Services C++ Programming Style Guidelines. This page list the most important things to keep in mind, as well as some guidelines that are different from those described in the Geotechnical Software Services's document.

Some other interesting references:

Editing

Indentation

  • Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Makefiles.
  • The indent size is 4 spaces.
  • You should configure your IDE accordingly:
    • With Xcode, in the tab Indentation of Xcode Preferences, let the checkbox Tab key insert tab, not spaces unckecked and set the Tab width as well as the Indent width parameters to 4.
    • With Eclipse, go to Window menu -> Preferences -> Coding Style, then edit the project settings and in the tab Indentation, set the Tab policy to Spaces only with Indentation size and Tab size set to 4.
    • With Visual Studio, go to Tools menu -> Options -> Text Editor -> C/C++ -> Tabs, set Tab Size and Indent Size to 4, and make sure Insert spaces is checked.

Braces

Always place the open brace { on the line preceding the code block; place the close brace } on its own line.

An example is worth a thousand words:

void ClassName::doSomething() {
    if (condition) {
        doThis();
    }
    else {
        doThat();
    }
}

Note that we use this block layout style for just about everything, that is for if/else blocks, for while or for loops, for functions and methods, classes and even namespaces. The main reason is that it's much simpler to use a single block layout style for everything.

Lines length

We try to keep lines short, under 80 columns; activating the print margin in Eclipse, or the page guide in Xcode can help.

Comments

We use // for all comments including multi-line comments, instead of /* [...] */.

Encoding, line endings

We always use UTF-8 as the file encoding, and the Unix style line endings.

Names

General rules

We use Java style names (mixed case, no underscore), members start with lower case letter, while classes start with upper case letters. Abbreviations and acronyms must not be uppercase when used as name (for example, we use AudioFileXiphFlacTagged instead of AudioFileXiphFLACTagged).

Members names and accessors

Non boolean members

  • Precede setters with the word set.
  • Use bare words for getters.
  • Setter and getter names should match the names of the variables being set/gotten.
  • Prefix C++ data members with the (when needed to avoid conflict with the name of the getter).

Using bare words for getters will ensure a certain level of coherence between C++ and Objective-C accessors names. Moreover, this is the convention used in big projects such as Qt (which is constantly used in TagAdA).

Boolean members

We use exactly the same naming conventions as described in Qt-Style documentation for boolean members.

Example

class Shape {
    
public:
    
    // Getters
    int size() const;
    bool isComplex() const;
    
    // Setters
    void setSize(int newSize);
    void setComplex(bool newComplexStatus);
    
private:
    
    // Private members
    int theSize;
    bool complex;
    
};

Note that you must declare getter methods as constant members functions: it will allow reading the content of an object even if declared as a constant object.

Null, false and 0

NULL, 0 or nil?

  • In C++, the null pointer value should be written as 0.
  • In C, it should be written as NULL.
  • In Objective-C and Objective-C++, follow the guideline for C or C++, respectively, but use nil to represent a null Objective-C object.

Note that in Objective-C, instance variables are initialized to zero automatically. Don't add explicit initializations to nil or NO in an init method.

Boolean values

C++ and C bool values should be written as true and false. Objective-C BOOL values should be written as YES and NO.

Tests

Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons.

Miscellaneous

#include directives

We put the #include directives in the .cpp files whenever they are not required in the headers file.

We can use #import directives instead of #include ones in Objective-C files (.m, .mm files, or .h files used only by Objective-C files).

Pointers and references

Both pointer types and reference types should be written with a space between the type and the * or & symbol (so the * or & symbol is adjacent to the following identifier if any).

This is contrary to most of C++ specific guidelines, but once more, we made this choice for the sake of coherence between C++ and Objective-C code.

We also prefer using references than pointers when possible.

Last modified 11 years ago Last modified on Dec 29, 2009, 6:14:59 PM
Copyright © 2008-2017 The TagAdA Team. All rights reserved.