 |
Workspace 6.21.5
|
|
Workspace 6.21.5
|
This document describes the coding standard used by the Workspace developers. It reflects the desired style and conventions to be used throughout the Workspace code base. Older code may not yet adhere to the advice given here, so such cases should be brought into compliance as developers encounter them where practical. For the most part, this standard addresses C and C++ code, but some items are applicable more broadly to other languages, tools or formats used or supported by the build system.
We welcome other groups adopting these coding standards for their own work. In particular, we encourage Workspace plugin developers to consider following these conventions so that others using their work will have a certain level of familiarity with the overall style.
| General | |
| Names | |
| Headers | |
| Comments | |
| Formatting | |
| Implementation | |
References | |
min, max, etc.).for loop counters are frequently named i, j or k iter (this differentiates them from ordinary integer counters such as i).impl instead of implementation.| Correct | Incorrect |
| SomeProgClass | Some_Prog_Class someProgClass Someprogclass |
| VtkWriter | VTKWriter |
| Application | APPLICATION |
| Correct | Incorrect |
| rectangle_ | rectangle |
| executionMode_ | executionMode ExecutionMode execution_mode |
const specifierconst specifier on a function parameter passed by value. The compiler silently ignores it when matching calls to the function.| Correct | Incorrect |
| getBigThings() | GetBigThings() get_big_things() getbigthings() GETBIGTHINGS() |
| getBigThings(int key, QString value) | getBigThings(int, QString) |
| getBigThings(int numItems) | getBigThings(int n) |
| getBigThings(double* ptr) | getBigThings(double *ptr) |
| getBigThings(int numItems) | getBigThings(const int numItems) |
m_ on the name.ptr or similar in the name for member variables that hold pointers.const keyword should be placed before the type, as in const QString& someVar.const char* someVar.const keyword has to be placed between the * and the variable name, as in char* const someVar.The rules for enums are the same as for class names. This applies to both the enum name (ie its type identifier) and to the names of its values (ie its enumerators).
The rules for typedefs are the same as those of the entity they are typedef'ing. For example, a typdef for a class should conform to class name rules.
The rules for XML tags are the same as for class names, except that all characters should be in lowercase.
This section covers naming items in the file system within the source tree. It is not necessarily meant to be applied to files created or used by the software at run-time, although the rules specified here would often be a useful guideline.
test_xxxx.cpp (see Tests).| Correct | Incorrect |
| somesourcefile.cpp | some_source_file.cpp someSourceFile.cpp |
| file1.cpp | 1file.cpp file_1.cpp |
| test_foobar.cpp | testfoobar.cpp foobar_test.cpp foobartest.cpp |
| foobar_win32.cpp foobar_mac.cpp foobar_linux.cpp | foobarwin32.cpp mac_foobar.cpp foobar-linux.cpp |
.html| File Type | Extension |
| C source | .c |
| C++ source | .cpp |
| C/C++ header | .h |
| C/C++ source with doxygen comments only | .dox |
| Qt Designer UI file | .ui |
| Qt resource file | .qrc |
| HTML source | .html |
| JPEG image | .jpg |
test_xxx.cpp where xxx is the name of the test and would follow the same rules as an ordinary C++ source file name.main() should be named test_xxx.cpp as above. Other source files follow the usual rules for source files.| Correct | Incorrect |
| test_foobar.cpp | testfoobar.cpp foobar_test.cpp foobartest.cpp |
const variables or enums, since those offer much better type safety than a #define.#define function macros for similar reasons.#define is used to define a value, the name of the symbol being defined should consist only of uppercase letters, numbers and underscores.#define contains more than one word, underscores can be used to separate the words for readability.#define is used to define a function macro, the name of the function macro and the names of the function macro's parameters should follow the same rules as for an ordinary function....impl.h headers._H.The standard form of a header guard is as follows:
// Copyright header would be included first....
#ifndef CSIRO_GUMBY_FOOBAR_H
#define CSIRO_GUMBY_FOOBAR_H
namespace CSIRO
{
namespace Gumby
{
class FooBar
{
// ...
};
}}
#endif
In header files, use forward declarations rather than a full #include if:
#define before headers, other than to work around a compiler limitation or bug.Do not put a using directive in a header file other than for one of the following cases:
using directive to the renamed symbol. The effect of the using directive should be kept to the minimum required in order to achieve backwards compatibility for the renamed symbol.#include any header on its own (whether internal or public) and not generate a compiler error due to missing symbols, etc.#include its own set of headers as necessary to provide that symbol)..h),.c, .cpp)CMakeLists.txt)The standard notice used for all Workspace code is the following:
============================================================================
Copyright 2023 by:
Commonwealth Scientific and Industrial Research Organisation (CSIRO)
This file is licensed by CSIRO under the copy of the CSIRO Binary
License Agreement included with the file when downloaded or obtained
from CSIRO (including any Supplementary License). If no copy was
included, you must obtain a new copy of the Software from CSIRO before
any use is permitted.
For further information, contact: workspace@csiro.au
This copyright notice must be included with all copies of the source code.
============================================================================
\brief statement at the top, followed by a blank line.\internal command on the first line, on its own.\internal directive is optional.\tparam and appear after the \brief section, but before the main description of the class.\relates or \sa (ie "see also") blocks should be included. These should be the last sections in the documentation block./**
* \brief Implements a specific magic trick
*
* This class does all sorts of interesting things.
* Most of it is magic, some is just pure genius.
*
* \relates PerformMagic
*/
class MagicTrick
{
// Contents of the public class
};
/**
* \brief Example of a template class
*
* \tparam TrickT Specifies the type of trick the class defines
*/
template<typename TrickT>
class PerformTrick
{
// Contents of the public class
};
/**
* \internal
*/
class HiddenSecret
{
// Move along, nothing to see here...
};
\param entry at the start of the comment block.\tparam and appear before the regular function parameters.\a doxygen command with it to ensure it is formatted correctly.\return command at the end of the comment block.\pre command, usually placed before or after the description (whichever is more readable)\post command.\sa (ie "see also") command.\sa command.\sa block should always be the last section in the documentation block. // ... end of previous function
}
/**
* \param xFactor Some value that does extra special things.
* \param required Switch specifying whether we want to use the \a xFactor.
*
* This function does some magical computation. It uses \a xFactor
* only when \a required is \c true. Otherwise, it uses some other value.
*
* \return The magic factor, or pi if you are hungry.
*
* \sa foolGeneralPublic()
*/
double computeMagic(double xFactor, bool required)
{
// ....
}
enum that is part of the public interface must be documented. A description of the enum (without using the \brief command) is sufficient.enum should also be documented.enum are usually placed after the item, as per the following example:/**
* Specifies what sort of magic tricks can be requested.
*/
enum SupportedMagicTricks
{
SleightOfHand, //!< Standard magician's trick
Misdirection, /*!< This can be a bit more involved which
is why its description is longer */
GrandIllusion //!< Not going to spoil the surprise!
};
| Correct | Incorrect |
| int varOne; int varTwo; | int varOne, varTwo; |
| int* varOne; int& varTwo = ...; | int *varOne; int &varTwo = ...; |
Virtual, Final and Override qualifiers should be present on a given method declaration in a class. Writing more than one of these three is redundant and a potential source of errors.Virtual keyword should only be used to declare a new virtual method on a class. It should not* be used on overrides in derived classes.Override qualifier should only be used to declare a non-final override of a base-class method.Final qualifier should only be used to declare a final override of a base-class method.#include <iostream>
class BaseClass
{
public:
virtual bool virtualMethod() const = 0;
};
class DerivedClassOne : public BaseClass
{
public:
void virtualMethod() const override
{
std::cout << "This implementation is a non-final override." << std::endl;
}
virtual newVirtualMethod() const
{
std::cout << "This implementation is a new virtual method." << std::endl;
}
};
class DerivedClassTwo : public BaseClass
{
public:
void virtualMethod() const final
{
std::cout << "This implementation is a final override." << std::endl;
}
};
// Example 1: good
std::array<int, 6> integers({1, 2, 3, 4, 5, 6});
// Example 2: good
std::array<double, 3> doubles({
0.0,
1.0,
2.0});
// Example 3: good
double cStyleDoubles[3] = {
0.0,
1.0,
2.0};
// Example 4: bad
float floats[3] =
{
0.0f,
1.0f,
2.0f
};
// Example 5: bad
const char* strings[3] = {
"oh",
"hi",
"there"
};
// Example 6: bad
std::array<float, 3> moreFloats(
{
"oh",
"hi",
"there"
});
// Example 1: good
auto result = someFunc([](auto& param) {
return 0.0;
});
// Example 2: good
auto result = someFunc([](auto& param) { return 0.0; });
// Example 3: bad
auto result = someFunc(
[](auto& param)
{
return 0.0;
});
// Example 4: bad
auto result = someFunc([](auto& param)
{
return 0.0;
});
/**
* Some bad code
*/
#define PRINT_VALUES(value1, value2) \
cout << value1; \
cout << ", "; \
cout << value2;
void someFunction(bool choice)
{
if(choice)
PRINT_VALUES(1, 2);
}
expands to:void someFunction(bool choice)
{
if(choice)
cout << 1;
cout << ", ";
cout << 2;
}
which is not what the writer would have intended. Always using braces avoids this pitfall.| Correct | Incorrect |
| if (someExpression == true) { // Do something } | if (someExpression == true) { // Do something } |
| Within a class definition only... int getFoobar() const { return foobar_; } | if (someExpression == true) { doSomething(); } |
| Correct | Incorrect |
| Foo::Foo(int a, int b) : a_(a), b_(b) {} | Foo::Foo(int a, int b) : // Something really long... ;) |
| Foo::Foo(int a, int b) : a_(a), b_(b) { } | Foo::Foo(int a, int b) : a_(a), b_(b) { } Foo::Foo(int a, int b) : a_(a) , b_(b) { } |
The indentation guidelines are best shown by example:
/**
* \brief Main outer namespace
*/
namespace A
{
/**
* \brief Inner namespace for fun toys
*
* To avoid excessive indenting, don't indent inner namespaces ....
*/
namespace B
{
// .... unless it is an anonymous or private namespace, in which
// case you can indent it or not depending on your own preference
namespace
{
// ...
}
/**
* \brief Does nothing interesting
*/
class Foo : public JustOneBase
{
// ...
};
/**
* \brief Does some more interesting things
*/
class Bar :
public BaseOne, // Indent multi-line base classes
public BaseTwo
{
double var1_;
// Access specifiers have same indentation as the class keyword
public:
Bar();
int getCrazyValue(int b);
/**
* \brief Inner class for interesting stuff
*/
class Nested
{
// ... Same rules as for regular non-nested classes
}
/**
* Toys for the adrenalin junky
*/
enum CoolThings
{
Snowboards, //!< For cold weather only
DrumKits //!< Use when neighbours are away
};
};
/**
* \param b Mystery switch
*
* \return A crazy value of little use.
*/
int Bar::getCrazyValue(int b)
{
int a = 1;
for (int i = 0; i != 20; ++i)
{ // Don't indent curly braces....
a += i; // ... only indent the stuff within the braces
}
switch (b)
{
case 7: // Don't indent the case keywords ...
a += 42; // ... but do indent the case body
break;
case 2:
a -= 27;
break;
default:
a += b;
}
return a;
}
}}
The following are a set of implementation guidelines not already covered by preceding sections. They are designed to provide some consistency in coding style and to avoid common programming pitfalls or suboptimal code. Many of these are discussed in more detail in the excellent book "C++ Coding Standards", by Herb Sutter.
pImpl_ in all Workspace code.const proactively. If a member function does not modify an object's data, make it const.const references from a const function.The following are in addition to the rules for ordinary member functions:
void.void since they should be designed primarily for code that will ignore any return value.See Scott Meyers' book "More Effective C++" for further good advice on exceptions.
logLine() instead of logText(), as logLine() automatically appends a carriage return at the end of the message you supply whereas logText() does not.auto numElems = container.size();for (auto i = decltype(numElems); i < numElems; ++i)goto.const_cast except to work around const-correctness bugs in third party code.reinterpret_cast except where required to be compatible with low level code (very rare).static_cast or dynamic_cast as appropriate instead.if or switch statements. Prefer proper class design with virtual functions or templated solutions.++ and -- operators over postfix. Eg, ++a is preferred over a++ where either could be used.assert(). Instead, use one of the Workspace assert macros defined in "Workspace/Application/LanguageUtils/errorchecks.h". They should be used liberally to verify any assumptions or as a defensive measure to catch problems early. Debug-only macros should be accompanied by equivalent protective code for Release.The following are some references that have had a strong influence on the Workspace source code, both in terms of style and implementation. They are highly recommended for anyone interested in C++ development in general.