Coding Conventions - Revision history

Impaktor: /* Code Formatting */

2021-01-25T10:35:50Z

‎Code Formatting

Sturnclaw at 02:08, 11 May 2020

2020-05-11T02:08:05Z

Sturnclaw at 02:02, 11 May 2020

2020-05-11T02:02:35Z

Sturnclaw at 02:00, 11 May 2020

2020-05-11T02:00:25Z

Sturnclaw: Unify coding style convention documentation.

2020-05-11T01:58:53Z

Unify coding style convention documentation.

Show changes

Sturnclaw: Update text and markup

2020-05-11T00:24:00Z

Update text and markup

Sturnclaw: Updated clang-format instructions.

2019-02-16T03:00:24Z

Updated clang-format instructions.

Sturnclaw: Add details on clang-format and the pre-commit hook.

2019-01-07T02:09:05Z

Add details on clang-format and the pre-commit hook.

Luomu: Imported from GH wiki

2012-09-16T21:52:08Z

Imported from GH wiki

New page

=== Classes ===

Class names in camel case starting with upper case like so:

<tt>class MyClass {};</tt>

Class member variables prefixed with <tt>m_</tt>, camel case starting with lower case:

<pre>
class MyClass {
public:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that to avoid verbosity the above is not followed for classes that are used more like structs, like vector3.

Class functions should be camel case starting with upper case:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camel case starting with lower case:

<tt>int g_screenWidth;</tt>

Variables with static scope should be prefixed with <tt>s_</tt>:

<tt>static int s_someGlobalForJustThisFile;</tt>

← Older revision		Revision as of 10:35, 25 January 2021
Line 58:		Line 58:
	This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.		This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

		+
		+	=== Disable ===
		+
		+	There are times when alignment is more sane to do manually, e.g. for matrices or other things, clang format can be disabled [https://clang.llvm.org/docs/ClangFormatStyleOptions.html#disabling-formatting-on-a-piece-of-code disable] for these.

	= C++ Code Formatting Guide =		= C++ Code Formatting Guide =

@@ Line 1: / Line 1: @@
 This page describes some of the code style used in Pioneer. As of 2019, we rely on clang to do our code-formatting checks for us. This means a Pull Request (PR) with incorrectly formatted code will fail the automated test. Please read [[Coding Conventions|Code Formatting]] for how to avoid this, and how to have our clang-format.sh script check your code before committing.
 == Licensing ==
@@ Line 57: / Line 59: @@
-== C++ Code Formatting Guide ==
+= C++ Code Formatting Guide =
 This section documents syntax and style guidelines that should be followed across the codebase.
@@ Line 67: / Line 69: @@
 There are a few abbreviated names that are commonly used throughout the codebase, eg <code>Renderer *r</code>, <code>lua_State *l</code>, etc. Try to prefer them where appropriate.
-=== Classes ===
+== Classes ==
 Class names should be written in PascalCase like so:
@@ Line 109: / Line 111: @@
 This includes static functions; they use the same naming convention as member functions, but their intended use should be well documented.
-=== Global variables ===
+== Global variables ==
 Global variables must be prefixed with <tt>g_</tt>, and use camelCase:
@@ Line 123: / Line 125: @@
 == Comments ==
 Generally, use the style of the file you're working on. But the below is the general principle for commenting code.
@@ Line 222: / Line 224: @@
 The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef</code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.
-== Include guards ==
+=== Include guards ===
 Pioneer is (slowly and unofficially) moving away from include guards and using <code>#pragma once</code> as it's easier, less accident-prone (name collisions anyone?), and well supported by all modern compilers. However, we're not rejecting code using include guards instead.
@@ Line 283: / Line 285: @@
 };
 </pre>

@@ Line 258: / Line 258: @@
      };
-=== C++-style Enum Class ===
+If you're writing new code and can't use C++-style enum classes, consider using C-style enums scoped in a struct to avoid polluting the global namespace.
 <pre>
@@ Line 281: / Line 269: @@
          THING_MAX
      };
 };
 </pre>

@@ Line 220: / Line 220: @@
   static constexpr double M_PI = 3.14159;
-The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef<code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.
+The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef</code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.
 == Include guards ==

@@ Line 49: / Line 49: @@
 <pre>
-$ cp scripts/pre-commit-hook.sh .git/hooks/pre-commit-hook
+$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
 </pre>
@@ Line 58: / Line 58: @@
 === Applying The Format Changes ===
-Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can run the below command, replacing <code>FILE...</code> with the paths to the files that need to be fixed.
+Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:
 <pre>
-~/.../pioneer $ clang-format -style=file -i FILE...
+$ ./autoformat
 </pre>
-This will direct clang-format to overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, but rather determine which changes will be made first (by running <code>git commit</code> or <code>scripts/pre-commit-hook.sh</code> to trigger the validation hook).
+This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

@@ Line 1: / Line 1: @@
 === Classes ===
-Class names in camel case starting with upper case like so:
+Class names should be written in PascalCase like so:
-<tt>class MyClass {};</tt>
+ class MyClass {};
-Class member variables prefixed with <tt>m_</tt>, camel case starting with lower case:
+Class-private or protected member variables should be prefixed with <tt>m_</tt>, using camelCase:
 <pre>
 class MyClass {
-public:
+protected:
      int m_someValue;
      std::string m_anotherValue;
@@ Line 15: / Line 15: @@
 </pre>
-Note that to avoid verbosity the above is not followed for classes that are used more like structs, like vector3.
+Note that to avoid verbosity the above is not followed for structures with public data members, like <tt>vector3</tt>.
-Class functions should be camel case starting with upper case:
+All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:
 <pre>
@@ Line 28: / Line 28: @@
 === Global variables ===
-Global variables must be prefixed with <tt>g_</tt>, and use camel case starting with lower case:
+Global variables must be prefixed with <tt>g_</tt>, and use camelCase:
-<tt>int g_screenWidth;</tt>
+Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.
-Variables with static scope should be prefixed with <tt>s_</tt>:
+Variables with static scope should be prefixed with <tt>s_</tt>, and similarly use camelCase:
-<tt>static int s_someGlobalForJustThisFile;</tt>
+ static int s_classScopeVariable;
 == Code Formatting ==

← Older revision		Revision as of 02:09, 7 January 2019
Line 35:		Line 35:

	<tt>static int s_someGlobalForJustThisFile;</tt>		<tt>static int s_someGlobalForJustThisFile;</tt>
		+
		+	== Code Formatting ==
		+
		+	The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.
		+
		+	=== Diagnosing Formatting Issues ===
		+
		+	If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.
		+
		+	=== Installing a Git Hook ===
		+
		+	Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.
		+
		+	<pre>
		+	$ cp scripts/pre-commit-hook.sh .git/hooks/pre-commit-hook
		+	</pre>
		+
		+	Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.
		+
		+	If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.
		+
		+	=== Applying The Format Changes ===
		+
		+	Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can run the below command, replacing <code>FILE...</code> with the paths to the files that need to be fixed.
		+
		+	<pre>
		+	~/.../pioneer $ clang-format -style=file -i FILE...
		+	</pre>
		+
		+	This will direct clang-format to overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, but rather determine which changes will be made first (by running <code>git commit</code> or <code>scripts/pre-commit-hook.sh</code> to trigger the validation hook).
		+
		+	A script to automatically apply the results of the clang-format validation pass is planned, but not currently written. Once it is created, applying the code format changes will be as simple as running a single script from the main pioneer directory, and confirming the changes you want to apply.