|
|
| (2 intermediate revisions by one other user not shown) |
| 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!)
| + | #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 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.
| |
| − | | |
| − | Comment for documenting C++ function (will be picked up by 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)
| |
| − | {
| |
| − |
| |
| − | Comment for the [http://eatenbyagrue.org/f/pioneer/codedoc/files/LuaBody-cpp.html LuaAPI].
| |
| − | | |
| − | /*
| |
| − | * 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
| |
| − | };
| |
