|
|
| 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 - xhalf*x*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
| |
| − | };
| |
