Code style - Revision history

Sturnclaw: Remove obsolete Code Style page (merged with Coding Conventions)

2020-05-11T02:46:11Z

Remove obsolete Code Style page (merged with Coding Conventions)

Impaktor: Add link to clang code format guide

2019-02-19T18:31:41Z

Add link to clang code format guide

Impaktor: /* Comments */

2015-12-05T19:50:17Z

‎Comments

Impaktor: Add description for comments

2015-12-05T19:48:48Z

Add description for comments

Impaktor: /* Tabs & spacing */

2015-10-07T11:43:00Z

‎Tabs & spacing

Impaktor: /* Tabs & spacing */

2015-10-07T09:51:16Z

‎Tabs & spacing

Impaktor: 2014 - > 2015

2015-08-10T14:33:49Z

2014 - > 2015

RobN: /* Licensing */

2014-01-21T02:54:43Z

‎Licensing

RobN: /* Name style */

2013-12-10T09:17:56Z

‎Name style

RobN: /* Name style */

2013-12-10T09:16:01Z

‎Name style

← Older revision		Revision as of 02:46, 11 May 2020
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-formating checks for us. This means a pull request (PR) with incorrectly formated code will fail the Travis test. Please read [[Coding Conventions]] ~~for how to avoid this, and how to have our clang-format.sh script check your code before comitting.~~	+	#REDIRECT [[Coding Conventions]]

−	~~== Licensing ==~~	+	This page has been merged with [[Coding Conventions]].
−
−	~~Engine and Lua code is [http://www.gnu.org/licenses/gpl.html GPL 3]. Assets (include Lua-based data files like ship defs) are [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3]~~
−
−	~~Include these two lines at the top of each file (suitably commented):~~
−
−	~~Copyright © 2008-2015 Pioneer Developers. See AUTHORS.txt for details~~
−	~~Licensed under the terms of the GPL v3. See licenses/GPL-3.txt~~
−
−	~~Copyright © 2008-2015 Pioneer Developers. See AUTHORS.txt for details~~
−	~~Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt~~
−
−	~~== Tabs & spacing ==~~
−
−	* Hard tabs, 4-space aligned.
−	* Inner spaces after tabs to align arguments on multiple lines, etc
−	* No trailing spaces, and don't indent blank lines
−	* Attention MS Windows users: lines end with ~~linefeed (LF), not carige return (CR) or both (CRLF). If you can not fix it in your editor, git can do it for you,~~ [~~http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace conf git].~~
−
−
−
−	~~== Comments ==~~
−
−	~~Generally, use the style of the file you're working on. But the below is the general principle for commenting code.~~
−
−	* Use C++ comments rather than C comment blocks.
−	* Many people work on the code, so please describe whenever function- and variable names are not enough.
−	* Especially comment when you think you're writing clever code
−
−	~~For documenting C++ functions one can use three <tt>///</tt> and it will be picked up by~~ [~~https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html Doxygen~~]:
−
−	~~///~~
−	~~/// Function to be used only if user is willing to accept the return type~~
−	~~/// Do not use if prone to depression.~~
−	~~///~~
−	~~void meaningOfLife()~~
−
−
−	~~Regular comment in code for other programmers mucking about (example code from Quake3):~~
−
−	~~float InvSqrt (float x){~~
−	~~float xhalf = 0.5f*x;~~
−	~~int i = (int)&x;~~
−
−	~~// I really should have documented this~~
−	~~i = 0x5f3759df - (i>>1);~~
−
−	~~x = (float)&i;~~
−	~~x = x(1.5f - xhalfx*x);~~
−	~~return x;~~
−	}
−
−
−	~~But please don't over-comment the code:~~
−
−	~~// entered if we are flying~~
−	~~if(isFlying)~~
−	{
−
−	~~For [http://eatenbyagrue.org/f/pioneer/codedoc/files/LuaBody-cpp.html LuaAPI~~] ~~we use naturaldocs, these are done in C-style comment blocks in the <tt>src/Lua*.cpp</tt> files.~~
−
−	/*
−	* Method: Fly
−	*
−	* Fly high in the sky
−	*
−	* > ship:fly()
−	*
−	* Availability:
−	*
−	* 2015
−	*
−	* Status:
−	*
−	* experimental
−	*/
−	~~static int l_fly_high_in_the_sky(lua_State *l)~~
−	{
−	~~// code goes here~~
−	~~return 0;~~
−	}
−
−	~~== Constants ==~~
−
−	* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible
−
−	~~== Name style ==~~
−
−	* Classes: FooBar
−	* Methods: FooBar
−	* Class members: m_fooBar
−	* Static members: s_fooBar
−	* Constants (defines and <tt>static const</tt>): FOO_BAR
−
−	Names should generally be chosen for what the thing represents. It shouldn't have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). Just name it so its crystal clear what it is.
−
−	~~(Exception: member variables have a <tt>m_</tt> or <tt>s_</tt> to disambiguate them from local names and to match C++ conventions).~~
−
−	~~There's also a few abbreviated names that are commonly used throughout the codebase, eg <tt>Renderer r</tt>, <tt>lua_State l</tt>, etc. Try to prefer them where appropriate.~~
−
−	~~== Include guards ==~~
−
−	~~Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:~~
−
−	* Ship.h
−	~~#ifndef SHIP_H~~
−
−	* WorldView.h
−	~~#ifndef WORLDVIEW_H~~
−
−	* graphics/Renderer.h
−	~~#ifndef GRAPHICS_RENDERER_H~~
−
−	~~== Enum types ==~~
−
−	~~Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.~~
−
−	Avoid assigning explicit integer values. Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable). If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.
−
−	~~enum Thing {~~
−	~~THING_FOO,~~
−	~~THING_BAR,~~
−	~~THING_BAZ,~~
−
−	~~THING_MAX~~
−	};

← Older revision		Revision as of 18:31, 19 February 2019
Line 1:		Line 1:
−	This page describes some of the code style used in Pioneer. ~~Its probably incomplete~~, ~~but it should be correct~~. ~~If you see something in~~ the ~~code that doesn't match what's described here~~, ~~this guide takes precedence (~~and ~~please submit a patch~~ to ~~fix it!)~~	+	This page describes some of the code style used in Pioneer. As of 2019, we rely on clang to do our code-formating checks for us. This means a pull request (PR) with incorrectly formated code will fail the Travis test. Please read [[Coding Conventions]] for how to avoid this, and how to have our clang-format.sh script check your code before comitting.

	== Licensing ==		== Licensing ==

@@ Line 30: / Line 30: @@
 * Especially comment when you think you're writing clever code
-For documenting functions one can use three <tt>///</tt> and it will be picked up by [https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html Doxygen]. For [http://eatenbyagrue.org/f/pioneer/codedoc/files/LuaBody-cpp.html LuaAPI] we use naturaldocs, these are done in C-style comment blocks in the <tt>src/Lua*.cpp</tt> files.
+For documenting C++ functions one can use three <tt>///</tt> and it will be picked up by [https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html Doxygen]:
   ///
@@ Line 62: / Line 60: @@
+  {
-Comment for the [http://eatenbyagrue.org/f/pioneer/codedoc/files/LuaBody-cpp.html LuaAPI].
+For [http://eatenbyagrue.org/f/pioneer/codedoc/files/LuaBody-cpp.html LuaAPI] we use naturaldocs, these are done in C-style comment blocks in the <tt>src/Lua*.cpp</tt> files.
   /*
@@ Line 84: / Line 82: @@
   	return 0;
+  }
 == Constants ==

@@ Line 19: / Line 19: @@
 * No trailing spaces, and don't indent blank lines
 * Attention MS Windows users: lines end with linefeed (LF), not carige return (CR) or both (CRLF). If you can not fix it in your editor, git can do it for you, [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace conf git].
 == Constants ==

@@ Line 18: / Line 18: @@
 * Inner spaces after tabs to align arguments on multiple lines, etc
 * No trailing spaces, and don't indent blank lines
 == Constants ==

@@ Line 7: / Line 7: @@
 Include these two lines at the top of each file (suitably commented):
-     Copyright © 2008-2014 Pioneer Developers. See AUTHORS.txt for details
+     Copyright © 2008-2015 Pioneer Developers. See AUTHORS.txt for details
      Licensed under the terms of the GPL v3. See licenses/GPL-3.txt
-     Copyright © 2008-2014 Pioneer Developers. See AUTHORS.txt for details
+     Copyright © 2008-2015 Pioneer Developers. See AUTHORS.txt for details
      Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

@@ Line 28: / Line 28: @@
 * Class members: m_fooBar
 * Static members: s_fooBar
-* Constants: FOO_BAR
+* Constants (defines and <tt>static const</tt>): FOO_BAR
 Names should generally be chosen for what the thing represents. It shouldn't have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). Just name it so its crystal clear what it is.
 There's also a few abbreviated names that are commonly used throughout the codebase, eg <tt>Renderer *r</tt>, <tt>lua_State *l</tt>, etc. Try to prefer them where appropriate.