Main | CodingStandard

Programming Guidelines and Coding Conventions

Table of Contents

Design Guidelines

  • Do not use Qt keywords, instead use the Q_XXXX versions.
  • All reusable components must include complete Doxygen documentation.
  • To the fullest extent possible, all reusable code should be as self-contained as possible.
  • All reusable code should be compiled into single static libraries with one header file.
  • No warnings or errors are allowed.
  • No random printf statements or messageboxes are allowed.
  • Except for simple getters and setters, place as much functionality as possible in source files.
  • Use Qt unit testing.
  • All reusable code must provide a test/demonstration application called TestApp.
  • For all reusable code, compile in all required resources.
  • To the fullest extent possible, avoid the use of global variables and contaminating the global namespace.
  • When possible, use const variables instead of #define value.
  • Any function that can be made const must be made const.
  • When possible, make variables const, especially references.
  • When creating a getter, only use the prefix "Get" when necessary.
  • Always use the new Qt5 connect syntax when possible, even for overloaded functions.
  • All enums need to be class enums.

Coding Conventions

Constants

#define A_DEFINED_VALUE 1
const long SomeConstant = 4;
const long AnotherConstantVariable = 6;

Enums

enum class AnEnum{Value1, Value2, Value3};

class SomeClass{
public:
    enum class Type{Type1, Type2};

    int value() const {return(m_Value);}
    void SetValue(int value) {m_Value = value;}

    Type GetType() const {return(m_Type);}
    void SetType(Type type) {m_Type = type;}

protected:
    int m_Value;
    Type m_Type;
};

if(something == AnEnum::Value1 || someClassInstance.GetType() == SomeClass::Type::Type1){
   ...
}

Local Variables

int aLocalVariable = 4;
int * pLocalVariable = &aLocalVariable;
int & rLocalVariable = aLocalVariable;
char text = "some text";
long computers[] = {1, 2, 3, 4, 5, 6};

Functions

void SomeFunction(long arg1, short arg2, long * pAddress);

Generic/reusable Qt-based classes

QSomeClass(long classSpecificVariable, QWidget * pParent = 0, Qt::WindowFlags f = 0);

Application specific Qt-based classes

SomeClass(long * pClassSpecificVariable, QWidget * pParent = 0, Qt::WindowFlags f = 0);

Type prefixes

int g_AGlobalVariable = 0;
int m_AMemberVariable = 1;
int * m_pAMemberVaribalePointer = &g_AGlobalVariable;
int localVariable = 2;
int * pLocalPointerVariable = &localVariable;
int & rLocalReferenceVariable = localVariable;

Example

somenewwidget.h:

#ifndef __SOME_NEW_WIDGET__
#define __SOME_NEW_WIDGET__

// System includes
#include <QWidget>

class QPushButton;

class SomeNewWidget : public QWidget{
    Q_OBJECT

public:
    enum class ButtonType{Hello, Goodbye};

    SomeNewWidget(ButtonType type, QWidget * pParent = 0);
    QSize sizeHint() const;  // Overridden Qt function.
    ButtonType Type() {return(m_Type);}

    Q_SLOT void SetType(ButtonType type);
    Q_SLOT void ButtonClick(bool checked);

protected:
    ButtonType m_Type;

    QPushButton * m_pPushButton1;
    QPushButton * m_pPushButton2;
};

#endif

somenewwidget.cpp

#include "somenewwidget.h"

// System includes
#include <QPushButton>
#include <QVBoxLayout>

SomeNewWidget::SomeNewWidget(ButtonType type, QWidget * pParent) : QWidget(pParent){
    setWindowTitle(tr("HMT Laboratory Coding Guidelines Example"));

    SetType(type);

    connect(m_pPushButton1, &QPushButton::clicked, this, &SomeNewWidget::ButtonClick);
    connect(m_pPushButton2, &QPushButton::clicked, this, &SomeNewWidget::ButtonClick);

    QVBoxLayout * pLayout = new QVBoxLayout(this);
    pLayout->addWidget(m_pPushButton1);
    pLayout->addWidget(m_pPushButton2);
    setLayout(pLayout);
}

void SomeNewWidget::SetType(ButtonType type){
    m_Type = type;

    if(type == ButtonType::Hello){
        m_pPushButton1 = new QPushButton(tr("Hello"), this);
        m_pPushButton2 = new QPushButton(tr("World"), this);
    }
    else{
        m_pPushButton1 = new QPushButton(tr("Good"), this);
        m_pPushButton2 = new QPushButton(tr("Bye"), this);
    }
}

void SomeNewWidget::ButtonClick(bool checked){
    // Currently not using the parameter checked.
    Q_UNUSED(checked);

    printf("A button was clicked.\n");
}

QSize SomeNewWidget::sizeHint() const {return(QSize(400, 150));}

main.cpp

// System includes
#include <QApplication>

// Application includes
#include "somenewwidget.h"

int main(int argc, char ** argv){
    QApplication app(argc, argv);
    SomeNewWidget someNewWidget(SomeNewWidget::ButtonType::Goodbye);

    someNewWidget.show();
    return(app.exec());
}