From 54a43de656a490e4bf30005827b2e10adb725502 Mon Sep 17 00:00:00 2001 From: Nikolai Kosjar Date: Wed, 16 Aug 2017 08:58:48 +0200 Subject: Add experimental .clang-format This adds a configuration file for clang-format [1] and a test file to demonstrate benefits and current problems with respect to Qt Creator's coding rules [2]. This is based on clang-format from the llvm/clang 5.0 branch, which is about to be released soon in the next days/weeks (already behind schedule). Using clang-format for Qt Creator brings these advantages: * Enforce a bunch of coding rules by a simple tool/shortcut invocation. * Spend less review cycles for authors and reviewers regarding formatting. This helps especially for/with first-time contributors. * clang-format sorts includes and using declarations. * clang-format adds/updates namespace end comments, e.g.: } // namespace Foo See dist/clangformat/README.md for setup instructions und currently known issues. [1] https://clang.llvm.org/docs/ClangFormat.html [2] https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html Task-number: QTCREATORBUG-17643 Change-Id: I87bdd66b8e492e99a360022962b0053f02a33e57 Reviewed-by: Alessandro Portale Reviewed-by: Eike Ziller --- dist/clangformat/.clang-format | 115 ++++++++++++++++++++++++++++++ dist/clangformat/README.md | 156 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100644 dist/clangformat/.clang-format create mode 100644 dist/clangformat/README.md (limited to 'dist/clangformat') diff --git a/dist/clangformat/.clang-format b/dist/clangformat/.clang-format new file mode 100644 index 0000000000..25df05eb26 --- /dev/null +++ b/dist/clangformat/.clang-format @@ -0,0 +1,115 @@ +# .clang-format for Qt Creator +# +# This is for clang-format >= 5.0. +# +# The configuration below follows the Qt Creator Coding Rules [1] as closely as +# possible. For documentation of the options, see [2]. +# +# Use ../../tests/manual/clang-format-for-qtc/test.cpp for documenting problems +# or testing changes. +# +# [1] https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html +# [2] https://clang.llvm.org/docs/ClangFormatStyleOptions.html +# +--- +Language: Cpp +AccessModifierOffset: -4 +AlignAfterOpenBracket: Align +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignEscapedNewlines: DontAlign +AlignOperands: true +AlignTrailingComments: true +AllowAllParametersOfDeclarationOnNextLine: true +AllowShortBlocksOnASingleLine: false +AllowShortCaseLabelsOnASingleLine: false +AllowShortFunctionsOnASingleLine: Inline +AllowShortIfStatementsOnASingleLine: false +AllowShortLoopsOnASingleLine: false +AlwaysBreakAfterReturnType: None +AlwaysBreakBeforeMultilineStrings: false +AlwaysBreakTemplateDeclarations: true +BinPackArguments: false +BinPackParameters: false +BraceWrapping: + AfterClass: true + AfterControlStatement: false + AfterEnum: false + AfterFunction: true + AfterNamespace: false + AfterObjCDeclaration: false + AfterStruct: true + AfterUnion: false + BeforeCatch: false + BeforeElse: false + IndentBraces: false + SplitEmptyFunction: false + SplitEmptyRecord: false + SplitEmptyNamespace: false +BreakBeforeBinaryOperators: All +BreakBeforeBraces: Custom +BreakBeforeInheritanceComma: false +BreakBeforeTernaryOperators: true +BreakConstructorInitializersBeforeComma: false +BreakConstructorInitializers: BeforeComma +BreakAfterJavaFieldAnnotations: false +BreakStringLiterals: false +ColumnLimit: 100 +CommentPragmas: '^ IWYU pragma:' +CompactNamespaces: false +ConstructorInitializerAllOnOneLineOrOnePerLine: false +ConstructorInitializerIndentWidth: 4 +ContinuationIndentWidth: 4 +Cpp11BracedListStyle: true +DerivePointerAlignment: false +DisableFormat: false +ExperimentalAutoDetectBinPacking: false +FixNamespaceComments: true +ForEachMacros: + - forever # avoids { wrapped to next line + - foreach + - Q_FOREACH + - BOOST_FOREACH +IncludeCategories: + - Regex: '^ + +## Prerequisites + + * clang-format >= 5.0 + +## Set up Qt Creator for use with clang-format + +### Install the configuration file + +For a given source file to format, clang-format it will read the configuration +from .clang-format in the closest parent directory for the file to format. + +Hence symlink/copy .clang-format from this directory to e.g. Qt Creator's top +level directory: + +For Linux/macOS: + + $ cd $QTC_SOURCE + $ ln -s dist/clangformat/.clang-format + +For Windows: + + $ cd $QTC_SOURCE + $ copy dist\clangformat\.clang-format # Do not forget to keep this updated + +### Configure Qt Creator + + 1. Enable the Beautifier plugin and restart to load it. + + 2. Configure the plugin: + In Menu: Tools > Options > Beautifier > Tab: Clang Format + * Select a valid clang-format executable + * Use predefined style: File + * Fallback style: None + + 3. Set shortcuts for convenience: + In Menu: Tools > Options > Environment > Keyboard + * ClangFormat / FormatFile - e.g. Alt+C, F + * ClangFormat / FormatSelectedText - e.g. Alt+C, S + +Due to several issues outlined below the FormatFile action might be of limited +use. + +## Coding rules enforced by clang-format + +This is a copy-pasted list of coding rules from + that can be +enforced with the current configuration: + +* Formatting + * Whitespace + * Use four spaces for indentation, no tabs. + * Always use only one blank line (to group statements together) + * Pointers and References: For pointers or references, always use a single + space before an asterisk (*) or an ampersand (&), but never after. + * Operator Names and Parentheses: Do not use spaces between operator names + and parentheses. + * Function Names and Parentheses: Do not use spaces between function names + and parentheses. + * Keywords: Always use a single space after a keyword, and before a curly + brace. + * Braces + * As a base rule, place the left curly brace on the same line as the start + of the statement. + * Exception: Function implementations and class declarations always have + the left brace in the beginning of a line + * Line Breaks + * Keep lines shorter than 100 characters + * Insert line breaks if necessary. + * Commas go at the end of a broken line. + * Operators start at the beginning of the new line. + * Namespaces: + * Put the left curly brace on the same line as the namespace keyword. + * Do not indent declarations or definitions inside. + * Optional, but recommended if the namespaces spans more than a few lines: + Add a comment after the right curly brace repeating the namespace. +* Patterns and Practices + * C++11 and C++14 Features / Lambdas: + * Optionally, place the lambda completely on one line if it fits. + * Place a closing parenthesis and semicolon of an enclosing function call + on the same line as the closing brace of the lambda. + +## Coding rules violated by clang-format + +* Formatting / Namespaces + * As an exception, if there is only a single class declaration inside the + namespace, all can go on a single line. Currently this ends up on several + lines, which is noisy. +* Patterns and Practices / C++11 and C++14 Features / Lambdas + * If you are using a lambda in an 'if' statement, start the lambda on a new + line. + +### Other undesired formattings + +For a more complete list of observations and problems, see the "// NOTE: " +comments in ../../tests/manual/clang-format-for-qtc/test.cpp. + +#### Manually aligned complex expressions in e.g. if-conditions are collapsed + +We want: + + if (someFancyAndLongerExpression1 + || someFancyAndLongerExpression2 + || someFancyAndLongerExpression3) { + return value; + } + +Current: + + if (someFancyAndLongerExpression1 || someFancyAndLongerExpression2 + || someFancyAndLongerExpression3) { + return value; + } + +#### connect() calls do not follow the standard two-line pattern + +In general, for middle-sized and longer connect() calls we want to follow this +two-line pattern. + + connect(sender, &SomeFancySender::signal, + receiver, &SomeFancyReceiver::slot); + +Current: + + connect(sender, + &SomeFancySender::signal, + receiver, + &SomeFancySender::slot); + +#### QTC_ASSERT and excess space after return keyword + +For QTC_ASSERT in combination with the return keyword, an excess space is added: + + QTC_ASSERT(headItem, return ); + -- cgit v1.2.1