You may now automate C++ code layout with clang-format

Data Management DM Notifications
#1

RFC-261 has been implemented. The layout rules in the DM C++ Style Guide (https://developer.lsst.io/coding/cpp_style_guide.html) have been adjusted to allow automatic code layout with clang-format.

Please especially note the following changes to the rules:

  • 6-0. Layout MAY be automated with clang-format using the LSST configuration. (this rule is new)
    Note that using clang-format is optional, but its output is explicitly compatible (when using the LSST configuration).

  • 6-5. The class declarations SHOULD have the following form:

    Now looks like:

class SomeClass : public BaseClass1, public BaseClass2, private BaseClass3 {
public:
    SomeClass() {}

protected:
    ...

private:
    ...
};

Note that in contrast to our previous convention, bases are now on one line and the opening brace is on the same line as well.

  • 6-6. Function declarations MAY have any of the following three forms:

Return type on the same line as function name, parameters on the same line if they fit.

ReturnType ClassName::functionName(Type parName1, Type parName2) {
    doSomething();
    ...
}

If you have too much text to fit on one line:

ReturnType ClassName::reallyLongFunctionName(Type parName1, Type parName2,
                                             Type parName3) {
    doSomething();
    ...
}

or if you cannot fit even the first parameter:

ReturnType LongClassName::reallyReallyReallyLongFunctionName(
        Type parName1, Type parName2, Type parName3) {  // 8 space indent
    doSomething();  // 4 space indent
    ...
}

Note that in all cases the opening brace is always on the same line as the closing parenthesis.

  • 6-12. A switch statement SHOULD have the following form:
    Now uses 4 spaces indentation instead of 2.

  • 6-16. The following white space conventions SHOULD be followed:
    Spaces around *, / and % are now optional instead of prohibited.

  • 6-20. Variables in declarations SHOULD be left aligned where possible. (deleted)

  • 6-21a. Alignment SHOULD be used wherever it enhances readability. (deleted)

The last two rules were inconsistently followed and are much better done by automated tooling such as clang-format.

While you may now freely use clang-format, please don’t apply it to all code in bulk as this will introduce needlessly big change sets. Instead, limit its usage to new code and files you are actively working on.

3 Likes