Acquaman Coding Conventions - acquaman/acquaman GitHub Wiki

Qt and C++

Acquman is written in C++, using the Qt library (currently version 4.8.4) for enhanced OOP functionality and to provide a basis from which the Acquaman GUI is derived. It is strongly recommended to use QtCreator to do all development for Acquaman, owing to the nature of the Qt meta object system and the qmake build system. For anyone new to Qt development, it is highly recommended to look at some of the many tutorials provided for Qt at the Qt tutorials website.

Naming

As far as possible Acquaman sticks to Qt conventions when it comes to naming classes, however because of the nature of the classes, they may also contain a prefix which denotes that a class is part of a specific project relating either to a specific beamline or facility. In general the following rules apply:

  • Classes are name like classes in Qt
  • Use a full description, not an abbreaviation
  • Prepend AM to general framework classes
  • Prepend CLS to classes that apply across the CLS
  • Prepend beamline specific to local classes
Qt:        QDoubleSpinBox
Framework: AMScanConfiguration
CLS:       CLSSIIS3820Scaler
Beamline:  SGMAppController

Formatting

In order to make code as unified across all classes as possible, team members should stick to these general rules for formatting code:

  • All classes, functions and variables should be in camel case (ie. each new word gets a capital letter, no underscores, classes start with a capital letter, all others do not)
  • For any given concept group the member variables, functions and signals are of the form:
Getters: <conceptName>
Setters: set<ConceptName>
Members: <conceptName>_
Signals: <conceptNameChanged>

eg.

class ClassType{
public:
    // Getters:
    int sumOfLengths();
    QString descriptionOfThings();

    // Setters:
    void setSumOfLengths(int newValue);
    void setDescriptionOfThings(const QString& newValue);

signals:
    // Signals:
    void sumOfLengthsChanged();
    void descriptionOfThingsChanged();

private:
    // Member Variables:
    int sumOfLengths_;
    QString descriptionOfThings_;
};
  • Use K&R Style braces
    • Class and function definitions have the brace on a new line
    • All other braces are on the same line
    • Cuddled braces for else statements are okay, but not required
class someClass 
{
public:
    void someFunction();
};
someClass::someFunction() 
{
    // ...
}
    if (isTrue()) {
        // Do Something
    }
    else
    {
        // Do the Other Thing
    }

or

    if (isTrue()) {
        // Do Something
    } else {
        // Do the Other Thing
    }
  • Use tabs for spacing (not spaces)

Ordering of Access Modifier Groups in Classes

In order to allow other team members to quickly find member variables or functions in a given class it is recommended to follow the ordering system:

  • public:
  • signals:
  • public slots:
  • protected slots:
  • protected:
  • private slots:
  • private:

Writing Widgets

When writing widgets or any UI element team members should abide by the following guidelines:

  • Use manual layouts and Signal/Slot connections
  • Do not use the UI Editor or QML
  • Do not hide Signal/Slot connections in UI
  • Do not use auto connected names

Comments

  • Use Doxygen style comments on all functions and members in header files (/// or /!* */)
  • Use additional regular comments in cpp file to explain complex details (// or /* */)
  • When writing comments, ensure that semicolons are only included if the comment is intended to comment out a line of code.

Wrong

    // I once took an English course; semi colons are fun!

Okay

    // A function to do some things. The things it does are not needed any more, so it has been commented out
    // void doSomething();

Doing so allows us to run code clean ups on commented out code periodically, by doing a regex search. Including semicolons in comments which are not code means a lot of false positives.