Commit 54a43de6 authored by Nikolai Kosjar's avatar Nikolai Kosjar

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's avatarAlessandro Portale <alessandro.portale@qt.io>
Reviewed-by: Eike Ziller's avatarEike Ziller <eike.ziller@qt.io>
parent 40683aaa
......@@ -29,6 +29,7 @@
.DS_Store
/.qmake.cache
/.qmake.stash
/.clang-format
Makefile*
Thumbs.db
core
......
# .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
# .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 );
QT -= gui
CONFIG += c++14 console
CONFIG -= app_bundle
SOURCES += test.cpp
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment