openboe/oboe
2
0
Fork 0
Code Issues 146 Pull Requests 4 Actions Packages Projects Releases Wiki Activity

Fiddling with the style guide

Browse Source
This commit is contained in:
Celtic Minstrel
2014-12-04 12:47:57 -05:00
parent 94d8717a0b
commit 7e07d195f9
1 changed files with 52 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
StyleGuide.md
View File

@@ -26,16 +26,16 @@ Include Guards
-------------- --------------
All headers should have an include guard. The preferred format of the All headers should have an include guard. The preferred format of the
include guard #define is BOE_COMPONENT_FILENAME. include guard `#define` is `BOE_COMPONENT_FILENAME`.
Possible components are: Possible components are:
* game - files specific to the game * `game` - files specific to the game
* data - files defining the game's data (currently kept in the classes * `data` - files defining the game's data (currently kept in the classes
folder) folder)
* pced - files specific to the player character editor * `pced` - files specific to the player character editor
* scened - files specific to the scenario editor * `scened` - files specific to the scenario editor
* dlog - files that are part of the DialogXML framework * `dlog` - files that are part of the DialogXML framework
The COMPONENT can be omitted if none of the above apply. The COMPONENT can be omitted if none of the above apply.
@@ -106,14 +106,14 @@ Never use a using namespace declaration in a header file. It's
acceptable in a source file, but discouraged. Using declarations are acceptable in a source file, but discouraged. Using declarations are
fine in source files, but not in header files unless they're in an fine in source files, but not in header files unless they're in an
inline function or class declaration. Namespace aliases are encouraged inline function or class declaration. Namespace aliases are encouraged
for long namespaces. When using std::bind within a function, always put for long namespaces. When using `std::bind` within a function, always put
a `using namespace std::placeholders;` line somewhere in the function. a `using namespace std::placeholders;` line somewhere in the function.
Don't use nested classes. Don't use nested classes.
Only put absolutely necessary functions in header files; if a function Only put absolutely necessary functions in header files; if a function
only needs to be used in one file, it shouldn't be in a header. In this only needs to be used in one file, it shouldn't be in a header. In this
case, it should be declared static. (Don't use an anonymous namespace case, it should be declared `static`. (Don't use an anonymous namespace
for this purpose.) for this purpose.)
Local variables should be declared as close to the point of use as Local variables should be declared as close to the point of use as
@@ -122,8 +122,8 @@ the top of the function, since this was required in C at that time;
don't do this in new code. don't do this in new code.
Whenever possible, eliminate global variables. It's accepted that some Whenever possible, eliminate global variables. It's accepted that some
global variables can;t be helped, such as the global cUniverse and the global variables can't be helped, such as the global `cUniverse` and the
global cScenario, but if a global is just being used to pass information global `cScenario`, but if a global is just being used to pass information
between disparate functions, find another way. There are such variables between disparate functions, find another way. There are such variables
in the code currently which we would like to eliminate. in the code currently which we would like to eliminate.
@@ -135,7 +135,7 @@ non-defaultable argument, unless you actually intend to define an
implicit conversion. An operator bool should usually be declared implicit conversion. An operator bool should usually be declared
explicit as well. explicit as well.
Generally, you should use the class keyword (rather than the struct Generally, you should use the `class` keyword (rather than the `struct`
keyword) to declare anything with member functions or non-public keyword) to declare anything with member functions or non-public
members. members.
@@ -161,78 +161,77 @@ Functions
If a function takes a parameter by reference or pointer and doesn't If a function takes a parameter by reference or pointer and doesn't
modify it, the parameter should be const. Don't declare parameters const modify it, the parameter should be const. Don't declare parameters const
if they are passed by value. Don't use const pointers for parameters (eg if they are passed by value. Don't use const pointers for parameters (eg
int*const). `int*const`).
Overloading functions is encouraged. Overloading functions is encouraged.
Default arguments are encouraged. Default arguments are encouraged.
Don't use throw() specifications Don't use `throw()` specifications.
General Coding Style General Coding Style
==================== ====================
Use of exceptions is encouraged, though you should ensure that they get Use of exceptions is encouraged, provided it makes sense, though you
caught somewhere before main(). should ensure that they get caught somewhere before `main()`.
Prefer C++-style casts to C-style casts. Prefer C++-style casts to C-style casts.
Do not use cout, clog, or cin. Do not include <iostream>. To write log Do not use `cout`, `clog`, `cerr`, or `cin`. Do not include `<iostream>`.
messages, use printf. All other C++ streams are permitted and in fact To write log messages, use `printf`. All other C++ streams are permitted
encouraged. Do not use sprintf for anything. and in fact encouraged. Do not use `sprintf` for anything.
Use const whenever it makes sense. In particular, declare string Use const whenever it makes sense. In particular, declare string
constants as const char*const. constants as `const char*const`.
Never use simple macros for constants. Create an enum instead. Macros Never use simple macros for constants. Create an enum instead. Macros
that take arguments may be acceptable, depending. that take arguments may be acceptable, depending.
Don't use 0 where a pointer is expected; use NULL or nullptr instead. Don't use 0 where a pointer is expected; use `NULL` or `nullptr` instead.
Feel free to use auto if it simplifies the code, but generally only for Feel free to use `auto` if it simplifies the code, but generally only for
local variables. local variables.
Don't use lambda expressions. Use of std::function and std::bind is Use of lambda functions, `std::function`, and `std::bind` is encouraged.
encouraged.
Use of Boost libraries is encouraged. Use of Boost libraries is encouraged.
Naming Rules Naming Rules
============ ============
Header files should have a .hpp extension. C++ source files should have Header files should have a "_.hpp_" extension. C++ source files should have
a .cpp extension, and Objective-C++ files should have a .mm extension. a "_.cpp_" extension, and Objective-C++ files should have a "_.mm_" extension.
Files specific to one component should be named with one of the prefixes Files specific to one component should be named with one of the prefixes
"boe.", "pc.", "scen.". "_boe._", "_pc._", "_scen._".
Sometimes, a header will define an interface that has to be implemented Sometimes, a header will define an interface that has to be implemented
differently depending on the platform. In this case, the naming should differently depending on the platform. In this case, the naming should
be as follows: be as follows:
* file.hpp * _file.hpp_
* file.win.cpp * _file.win.cpp_
* file.mac.mm (or file.mac.cpp) * _file.mac.mm_ (or _file.mac.cpp_ if it doesn't include Objective-C code)
* file.linux.cpp * _file.linux.cpp_
If the Mac and Linux implementation happen to be the same due to only If the Mac and Linux implementation happen to be the same due to only
using POSIX headers, use "file.posix.cpp". using POSIX headers, use "_file.posix.cpp_".
For files containing inline template definitions, an extension of For files containing inline template definitions, an extension of
.tpl.hpp is preferred. "_.tpl.hpp_" is preferred.
In general, functions and variables should always start with a lowercase In general, functions and variables should always start with a lowercase
letter. Both underscore_separated and camelCase names are acceptable. letter. Both `underscore_separated` and `camelCase` names are acceptable.
Enums should be named with a lowercase e followed by an uppercase Enums should be named with a lowercase `e` followed by an uppercase
letter. letter.
Classes should either start with an uppercase letter or a lowercase c Classes should either start with an uppercase letter or a lowercase `c`
followed by an uppercase letter. followed by an uppercase letter.
Typedef or using declarations should usually end with _t. Typedef or using declarations should usually end with `_t`.
Do not use a trailing underscore or m_ prefix for member variables. Do not use a trailing underscore or `m_` prefix for member variables.
Names of constants (both enum constants and other constants) should Names of constants (both enum constants and other constants) should
either be all uppercase and separated by underscores, or camelCase either be all uppercase and separated by underscores, or camelCase
@@ -241,23 +240,30 @@ starting with a lowercase k followed by an uppercase letter.
Macros, when present, should be all uppercase and separated by Macros, when present, should be all uppercase and separated by
underscores. underscores.
Comments Comments and Annotations
======== ========================
Generally, C++-style comments are preferred, but feel free to use Generally, C++-style comments are preferred, but feel free to use
C-style comments for longer comments. C-style comments for longer comments.
If we ever introduce Doxygen comments, they will be in the Javadoc style If we ever introduce Doxygen comments, they will be in the Javadoc style
- block comments start with /**, line comments start with ///, and - block comments start with `/**`, line comments start with `///`, and
directives start with @. directives start with `@`.
Comment whenever something's purpose may be unclear. If you're uncertain Comment whenever something's purpose may be unclear. If you're uncertain
of something's purpose, feel free to add a TODO: comment. Use TODO for of something's purpose, feel free to add a `TODO:` comment. Use `TODO:` for
anything that is temporary or not perfect, or in places where there anything that is temporary or not perfect, or in places where there
needs to be code that hasn't been written yet. needs to be code that hasn't been written yet.
For organizing the function popup menu, use MARK: comments rather than For organizing the function popup menu, use `MARK:` comments rather than
#pragma mark. `#pragma mark`.
To mark parameters as unused, omit the name or surround it in block
comment syntax. Other unused entities should be removed or commented out
if you want to avoid warnings, though if you think it might have a use
in the future, it's reasonable to leave it in with a comment. Do not use
any kind of attributes, including `__attribute__`, `__declspec`, and
C++11 attributes.
Formatting Formatting
========== ==========
@@ -285,7 +291,8 @@ In declarations of pointers and references, the pointer or reference
operator should bind to the type, not the variable. Never declare operator should bind to the type, not the variable. Never declare
another type in the same declaration as a pointer or reference. another type in the same declaration as a pointer or reference.
Do not put parentheses around return values. Do not put parentheses around return values. Do not put redundant
parentheses around comparisons mixed in with logical operators.
If a constructor initializer must be wrapped, put the colon on the first If a constructor initializer must be wrapped, put the colon on the first
line and one variable per line thereafter. line and one variable per line thereafter.