summaryrefslogtreecommitdiff
path: root/dist/clangformat
diff options
context:
space:
mode:
authorNikolai Kosjar <nikolai.kosjar@qt.io>2017-08-16 08:58:48 +0200
committerNikolai Kosjar <nikolai.kosjar@qt.io>2017-09-04 06:53:55 +0000
commit54a43de656a490e4bf30005827b2e10adb725502 (patch)
treea72deca4c9ab7eb7a58c0256ba05be5e0967f188 /dist/clangformat
parent40683aaa4e461553289ae79fdae344084c43ca1c (diff)
downloadqt-creator-54a43de656a490e4bf30005827b2e10adb725502.tar.gz
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 <alessandro.portale@qt.io> Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Diffstat (limited to 'dist/clangformat')
-rw-r--r--dist/clangformat/.clang-format115
-rw-r--r--dist/clangformat/README.md156
2 files changed, 271 insertions, 0 deletions
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: '^<Q.*'
+ Priority: 200
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+IndentWidth: 4
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+# Do not add QT_BEGIN_NAMESPACE/QT_END_NAMESPACE as this will indent lines in between.
+MacroBlockBegin: ""
+MacroBlockEnd: ""
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 4
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 150
+PenaltyBreakBeforeFirstCallParameter: 300
+PenaltyBreakComment: 500
+PenaltyBreakFirstLessLess: 400
+PenaltyBreakString: 600
+PenaltyExcessCharacter: 50
+PenaltyReturnTypeOnItsOwnLine: 300
+PointerAlignment: Right
+ReflowComments: false
+SortIncludes: true
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: true
+SpaceAfterTemplateKeyword: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInContainerLiterals: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Cpp11
+TabWidth: 4
+UseTab: Never
diff --git a/dist/clangformat/README.md b/dist/clangformat/README.md
new file mode 100644
index 0000000000..ae714aad9e
--- /dev/null
+++ b/dist/clangformat/README.md
@@ -0,0 +1,156 @@
+# .clang-format for Qt Creator
+
+Alongside this file you find an EXPERIMENTAL .clang-format configuration file
+for the Qt Creator code base.
+
+The current configuration is useful, but not fully in accordance with the
+coding rules. There is also other undesired formatting. Running clang-format
+blindly will not only improve formatting here and there, but will also
+normalize/worsen code that is already considered ideally formatted. See section
+"Coding rules violated by clang-format" below for more information.
+
+If needed, clang-format can be instructed to not format code ranges. Do not
+overuse this.
+
+ // clang-format off
+ void unformatted_code ;
+ // clang-format on
+
+For more information about clang-format, see
+
+ <https://clang.llvm.org/docs/ClangFormat.html>
+
+## 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
+<https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html> 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 );
+