Difference between revisions of "New code guidelines"
m (→Enums) |
(//* comment style to /// style) |
||
Line 73: | Line 73: | ||
Q_OBJECT | Q_OBJECT | ||
public: | public: | ||
− | // | + | /// Constructs MyClass without initializing foo management |
explicit MyClass(QObject *parent = NULL); | explicit MyClass(QObject *parent = NULL); | ||
− | // | + | /// Constructs MyClass for managing initialFooCount of foos |
MyClass(int initialFooCount, QObject *parent = NULL); | MyClass(int initialFooCount, QObject *parent = NULL); | ||
... | ... | ||
Line 85: | Line 85: | ||
... | ... | ||
private: | private: | ||
− | // | + | /// Stores the number of foos since the last reset |
int m_fooCount; | int m_fooCount; | ||
}; | }; | ||
Line 117: | Line 117: | ||
* Comment in header / at point of declaration | * Comment in header / at point of declaration | ||
* Use doxygen style <nowiki>/** @brief Brief comment ...*/</nowiki> comments for bigger comments | * Use doxygen style <nowiki>/** @brief Brief comment ...*/</nowiki> comments for bigger comments | ||
− | * Use <nowiki>// | + | * Use <nowiki>///</nowiki> for one liners. |
* Place comments directly above the code they are referring to. Don't place them in the same line. | * Place comments directly above the code they are referring to. Don't place them in the same line. |
Revision as of 16:55, 18 September 2013
This is a work in progress meant as the basis for a discussion and doesn't reflect any kind of consensus. --DD0T 17:27, 17 September 2013 (UTC)
Contents
General
- The 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
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
- Use camelCase(Type camelCase)
- Getters: getVariable() (boolean: isVariable() / hasVariable() )
- Setters: setVariable()
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
- CamelCase
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.
- 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)
/** * @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
switch (foo) { case A: ... break; case B: case C: ... // Fall through default: break; }
- Each case/default must have a break or a return. Fall throughs must be explicitly commented.
- 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 /** @brief Brief comment ...*/ comments for bigger comments
- Use /// for one liners.
- Place comments directly above the code they are referring to. Don't place them in the same line.