Difference between revisions of "New code guidelines"

From Mumble Wiki
Jump to: navigation, search
(Code style)
(Redirected page to Coding Guidelines)
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''This is a work in progress meant as the basis for a discussion and doesn't reflect any kind of consensus. --[[User:DD0T|DD0T]] 17:27, 17 September 2013 (UTC) '''
+
#REDIRECT [[Coding Guidelines]]
 
 
= General =
 
* The [http://qt-project.org/wiki/Coding-Conventions Qt coding conventions] mostly apply
 
* Every source file should contain a license header
 
* Lines should generally be no longer than 100 characters
 
* Use newlines for logical grouping
 
* Try to be standards (C++03) compliant and const correct
 
* When interfacing with system code feel free to locally use the coding style recommended for that system
 
* Consistency is important but these are no laws. Use your own judgement.
 
 
 
= Headers =
 
* Include guards should use MUMBLE_FILENAME_H_ to prevent ambiguity
 
* Try to use forward declarations where possible to reduce coupling
 
 
 
= Naming =
 
* Don't abbreviate names.
 
* Good naming is essential for code maintainability. Treat it accordingly.
 
 
 
== Classes ==
 
* Use CamelCase names.
 
 
 
=== Member functions ===
 
* Arguments as well as function names should be camelCase
 
Type camelCase(Type camelCase);
 
* Getters should be prefixed with get/is/has, be constant and name the variable they return
 
Type getVariable() const;
 
/// Or for boolean
 
bool isVariable() const;
 
/// or
 
bool hasVariable() const;
 
* Setters should be prefixed with set and efficiently handle their argument
 
void setVariable(const Type& variable);
 
 
 
=== Qt Slots ===
 
* Use an "on" prefix onSomethingHappening() for manually wired slots
 
* Feel free to use Qt auto-wire where possible (e.g. on_qpbRemove_clicked())
 
 
 
=== Member variables ===
 
* m_camelCase
 
== Constants ==
 
* Use ALL_CAPS with underscore as a seperator
 
const Type ALL_CAPS;
 
 
 
== Types ==
 
* Use CamelCase for type names
 
 
 
== Enums ==
 
* Use CamelCase for enumeration types
 
* For disambiguation and improved auto-completion use a unique prefix for the enum variables. Prefer the capital letters in the CamelCase name if possible.
 
 
 
enum CamelCase {CC_FIRST, CC_SECOND, CC_THIRD};
 
 
 
* If you need an end marker for an enumeration prefer COUNT_PREFIX
 
* If the enumeration values need explanation use multiple lines
 
 
 
enum CamelCaseToo {
 
    /// First camel in the case
 
    CCT_FIRST,
 
    COUNT_CCT
 
};
 
 
 
= Code style =
 
* if statements
 
if (a > b
 
    || b > c
 
    || c > d) {
 
    doSomething();
 
} else {
 
    doSomethingElse();
 
}
 
* Split up long if statements at operators. Place the operators at the beginning of the new line instead of at the end.
 
* Try to keep the logic in if statements understandable. E.g. use additional named variables or split one if statement into multiple statements if it makes the code more readable.
 
* Always use { } unless there is no chance of misinterpreting the statement (e.g. returns)
 
if (thingy)
 
    return stuff;
 
 
 
* Classes (e.g. a QObject based class)
 
** Access specifiers should always be ordered public, public slots, signals, protected, private
 
** QObject derived classes must have a Q_OBJECT statement to ensure signal/slot is working
 
** Constructors with only one argument must be marked explicit
 
 
 
/**
 
  * @brief Class for managing things by foo.
 
  */
 
class MyClass : public QObject {
 
    Q_OBJECT
 
public:
 
    /// Constructs MyClass without initializing foo management
 
    explicit MyClass(QObject *parent = NULL);
 
    /// Constructs MyClass for managing initialFooCount of foos
 
    MyClass(int initialFooCount, QObject *parent = NULL);
 
    ...
 
public slots:
 
    ...
 
signals:
 
    ...
 
protected:
 
    ...
 
private:
 
    /// Stores the number of foos since the last reset
 
    int m_fooCount;
 
};
 
 
 
* Switch
 
** Each case/default must have a break or a return. Fall throughs must be explicitly commented.
 
 
 
switch (foo) {
 
    case A:
 
          ...
 
          break;
 
    case B:
 
    case C:
 
          ...
 
          // Fall through
 
    default:
 
          break;
 
}
 
 
 
* Constructors
 
Foo::Foo(int a, QObject *parent)
 
    : QObject(parent)
 
    , m_a(a) {
 
 
    doStuff();
 
};
 
 
 
= Comments =
 
Try to use comments in a sensible way. Don't comment the obvious (e.g. no setBla() "Sets bla") and don't feel obligated to comment every single parameter and function if the variable naming and types already make the behavior obvious.
 
 
 
Comment intent over behavior. Prefer
 
 
 
== Classes / Functions ==
 
* Comment in header / at point of declaration
 
* Use doxygen style comments
 
 
 
/**
 
  * @brief Use this for a big comment
 
  * @param parameter Takes param in meters
 
  * @return parameter in feet on success. A value < 0 on failure.
 
  */
 
 
 
  /// Use this for single line comments
 
 
 
* Place comments directly above the code they are referring to. Don't place them in the same line.
 

Latest revision as of 21:26, 8 March 2014

Redirect to: