diff options
| -rw-r--r-- | .clang-format | 87 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 27 |
2 files changed, 84 insertions, 30 deletions
diff --git a/.clang-format b/.clang-format index 6c1bd895e..1ac51fa4f 100644 --- a/.clang-format +++ b/.clang-format @@ -1,26 +1,47 @@ -# Not the exact style guide but enough for basic clang-tidy fix-its +--- Language: Cpp BasedOnStyle: LLVM -AlignAfterOpenBracket: AlwaysBreak -BreakConstructorInitializers: AfterColon -ConstructorInitializerAllOnOneLineOrOnePerLine: true -PointerAlignment: Middle -SortIncludes: false -SpacesBeforeTrailingComments: 2 -UseTab: Always -MaxEmptyLinesToKeep: 5 - -TabWidth: 4 +ColumnLimit: 120 +UseTab: ForContinuationAndIndentation ConstructorInitializerIndentWidth: 4 ContinuationIndentWidth: 4 -IndentWidth: 4 +TabWidth: 4 IndentCaseLabels: true +IndentWidth: 4 +# Spacing rules +SpaceAfterCStyleCast: true +SpaceAfterLogicalNot: false +SpaceAfterTemplateKeyword: true +SpaceBeforeAssignmentOperators: true +SpaceBeforeCpp11BracedList: true +SpaceBeforeCtorInitializerColon: true +SpaceBeforeInheritanceColon: true +SpaceBeforeParens: ControlStatements +SpaceBeforeRangeBasedForLoopColon: true +SpaceInEmptyParentheses: false +SpacesBeforeTrailingComments: 2 +SpacesInLineCommentPrefix: + Minimum: 1 + Maximum: 1 +SpacesInAngles: false +SpacesInContainerLiterals: false +SpacesInCStyleCastParentheses: false +SpacesInParentheses: false +SpacesInSquareBrackets: false +SpaceBeforeSquareBrackets: false + +# # Ensure spaces after commas +# SpaceAfterComma: true + +# Bracing and alignment +# BreakBeforeBraces: Allman BreakBeforeBraces: Custom BraceWrapping: + AfterCaseLabel: true AfterClass: true - AfterControlStatement: true + AfterControlStatement: Always AfterEnum: true AfterExternBlock: true AfterFunction: true @@ -29,9 +50,49 @@ BraceWrapping: AfterUnion: true BeforeCatch: true BeforeElse: true + BeforeLambdaBody: true + BeforeWhile: true IndentBraces: false SplitEmptyFunction: true SplitEmptyRecord: true + SplitEmptyNamespace: true +AllowShortCaseLabelsOnASingleLine: true +AllowShortCaseExpressionOnASingleLine: true +AlignConsecutiveShortCaseStatements: + Enabled: true + AcrossEmptyLines: true + AcrossComments: true + AlignCaseColons: false +AlignOperands: DontAlign +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignEscapedNewlines: Left +AlignTrailingComments: false +AlignAfterOpenBracket: BlockIndent + +# Function declarations +BinPackParameters: false +AllowShortFunctionsOnASingleLine: Inline +AllowAllParametersOfDeclarationOnNextLine: false +ExperimentalAutoDetectBinPacking: false + +# Line breaks +KeepEmptyLines: + AtEndOfFile: false + AtStartOfBlock: true + AtStartOfFile: true +MaxEmptyLinesToKeep: 5 + +# Misc +AllowAllArgumentsOnNextLine: false +BinPackArguments: false +BreakConstructorInitializers: AfterColon +BreakInheritanceList: AfterComma +PackConstructorInitializers: NextLineOnly +PointerAlignment: Middle +SortIncludes: false +PenaltyReturnTypeOnItsOwnLine: 1000000 +InsertNewlineAtEOF: true # Always include globals first IncludeCategories: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1644cba0f..e372896ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,24 +10,20 @@ If you are new to open source and/or GitHub, or just aren't sure about some deta Code Conventions ---------------- -When contributing, you must follow our code conventions. Otherwise, CI builds will automatically fail and your PR will not be merged until the non-conforming code is fixed. Due to this, we strongly advise you to run `src/CheckBasicStyle.lua` before committing, it will perform various code style checks and warn you if your code does not conform to our conventions. `CheckBasicStyle.lua` can be configured to run automatically before every commit via a pre-commit hook, **this is highly recommended**. There are instructions on how to achieve this at the bottom of this file. +When contributing, you must follow our code conventions. Otherwise, your PR may not be merged, or may fail its CI build. + +For code formatting, we use `clang-format` and a `.clang-format` file is present in the root of the repository. Most IDEs can integrate with clang-format and automatically reflow your code upon save. If not, it can be run manually or added as a pre-commit hook. The CI build will check your code and make sure there are no changes needed. We also provide a `.editorconfig` file. + +Other code style checks are performed by the `src/CheckBasicStyle.lua` script. We strongly advise you to run this before committing, it will perform various code style checks and warn you if your code does not conform to our conventions. `CheckBasicStyle.lua` can be configured to run automatically before every commit via a pre-commit hook, **this is highly recommended**. There are instructions on how to achieve this at the bottom of this file. Here are the conventions: - We use C++17. - - Please use **tabs for indentation and spaces for alignment**. This means that if it's at line start, it's a tab; if it's in the middle of a line, it's a space. - - All functions in all classes need documenting comments on what they do and what behavior they follow, use doxy-comments formatted as `/** Description */`. Do not use asterisks on additional lines in multi-line comments. - - Use spaces after the comment markers: `// Comment` instead of `//Comment`. A comment must be prefixed with two spaces if it's on the same line with code: - - `SomeFunction()<Space><Space>//<Space>Note the two spaces prefixed to me and the space after the slashes.` + - All functions in all classes need documenting comments on what they do and what behavior they follow, use doxy-comments formatted as `/** Description */` - All variable names and function names use CamelCase style, with the exception of single letter variables. - `ThisIsAProperFunction()` `This_is_bad()` `this_is_bad()` `GoodVariableName` `badVariableName`. - All private member variables start with `m_`, function parameters start with `a_`, class names start with `c`. - `class cMonster { int m_Health; int DecreaseHealth(int a_Amount); }` - - Put spaces after commas. `Vector3d(1, 2, 3)` instead of `Vector3d(1,2,3)` - - Put spaces before and after every operator, except unary operators. - - `a = b + c;` - - `if (a == b)` - - `++itr` - Keep individual functions spaced out by 5 empty lines, this enhances readability and makes navigation in the source file easier. - Add those extra parentheses to conditions, especially in C++: - `if ((a == 1) && ((b == 2) || (c == 3)))` instead of ambiguous `if (a == 1 && b == 2 || c == 3)` @@ -35,10 +31,6 @@ Here are the conventions: - Alpha-sort stuff that makes sense alpha-sorting—long lists of similar items etc. - White space is free, so use it freely. - "freely" as in "plentifully", not "arbitrarily". - - All `case` statements inside a `switch` need an extra indent. - - Each and every control statement deserves its braces. This helps maintainability later on when the file is edited, lines added or removed - the control logic doesn't break so easily. - - The only exception: a `switch` statement with all `case` statements being a single short statement is allowed to use the short brace-less form. - - These two rules really mean that indent is governed by braces. - Function parameters that are coordinates should be passed using an appropriate storage container, and not as three separate arguments. - e.g. for a block position, Vector3i. For an entity position, Vector3d. For a chunk coordinate, cChunkCoords. - For a 3-dimensional box of blocks, use cCuboid. For an axis-aligned bounding box, use cBoundingBox. @@ -58,10 +50,10 @@ Here are the conventions: - Instead of checking for a specific value, use an `IsXXX` function, if available: - `cPlayer:IsGameModeCreative()` instead of` (cPlayer:GetGameMode() == gmCreative)` (the player can also inherit the gamemode from the world, which the value-d condition doesn't catch). - All `#include` directives are specified relative to the root source directory. - - Add an empty last line in all source files (GCC and Git can complain otherwise). Pre-commit Hook --------------- + When contributing, the code conventions above *must* be followed. Otherwise, the CI builds will automatically fail and your PR will not be merged until the non-conforming code is fixed. It is highly recommended to set up a pre-commit hook which will check your code style before every commit. Here is how to do that: - Clone the repository as usual. @@ -80,17 +72,18 @@ Note that the check script is not smart enough to catch everything, so not havin Github-related conventions -------------------------- + The following rules are not strictly enforced, but if you follow them, you will make it easier for us to review your changes. - Use good short title for your PRs. `Store Health as float` is good, `Fix #4024` is not good. - If a PR fixes an issue, mention it in the PR description, but **not** in the commits themselves. Typically, we add the line `Fixes #007` to the bottom of the PR description, this makes Github link the PR to the issue, auto-close the issue when the PR is merged, and also is included in the merge message. - Focus on one thing only. Each PR should avoid making unrelated changes - those makes the history more difficult to understand later on, and they make the review a headache. - Feel free to rebase, amend or otherwise manipulate the commits in the PR (of course, as long as you're the only one working on the PR). We mostly squash-merge PRs, so your internal commit structure will not be important in the end. - If the PR is about one change, but it makes sense to keep the change broken into several commits, make sure each such commit is compilable, encapsulated, and possibly add a note to the PR description so that we consider this. - + Copyright --------- -Your must either place your work in the public domain or licensed it under the Apache License 2.0, and if so you must add yourself to the contributors file to show that you accept the publication of your work under the license. +Your must either place your work in the public domain or license it under the Apache License 2.0, and if so you must add yourself to the contributors file to show that you are publishing your work under that license. **PLUGINS ONLY**: If your plugin is not licensed under the Apache License 2.0, then it must be compatible and marked as such. This is only valid for the plugins included within the Cuberite source; plugins developed on separate repositories can use whatever license they want. |