138 lines
5.2 KiB
Plaintext
138 lines
5.2 KiB
Plaintext
Buildat conventions
|
|
===================
|
|
C++ Coding style
|
|
----------------
|
|
Using the correct coding style is important. If you are asked to fix your style
|
|
to follow the one defined here in every detail, do it carefully.
|
|
|
|
If something is found to be missing from this document, such additions shall be
|
|
made.
|
|
|
|
util/codestyle.sh:
|
|
A code formatting script. Always run before committing. It handles most
|
|
whitespace issues. Requires Uncrustify (http://uncrustify.sourceforge.net/).
|
|
|
|
Commit your changes temporarily before running the script, as it will not save
|
|
any kind of backups of the files.
|
|
|
|
If something seems wrong or weird, use the -a flag to enable annotations in code
|
|
to check if the script knows what it's doing or not.
|
|
|
|
Identifiers:
|
|
- Class and struct names are CamelCase,
|
|
- All function names are lowercase_with_underscores,
|
|
- All variable names are lowercase_with_underscores,
|
|
- All member variables start with m_. If the struct in question is a stupid data
|
|
container, this does not need to be followed.
|
|
|
|
Never use "class", always use "struct".
|
|
|
|
Prefer lightweight interfaces with a creation function for the default
|
|
implementation, like "struct State" and "State* createState()". The default
|
|
implementation can be called "CState" in this case, if an obviously better name
|
|
does not exist.
|
|
|
|
Use std::unique_ptr and std::shared_ptr. (core/types.h: up_<> and sp_<>)
|
|
|
|
Header files must have zero preprocessor conditionals, with the exception of
|
|
headers in src/ports/.
|
|
|
|
Function naming:
|
|
- Suffix _u: Unsafe, not included in public interface
|
|
|
|
Naming:
|
|
- "type": Numeric id representing a type
|
|
- "name": A string; generally works as an identifier but not necessarily
|
|
- "id": Numeric id of an instance of something that is not a type
|
|
- "sub": Subscription; a means to trigger something based on something else
|
|
happening; data goes from the emitter to the subscriber
|
|
- "hook": A callback that can modify some of the source's data or behavior
|
|
before the source goes on with it
|
|
|
|
Logging:
|
|
- Use core/log.h. Only use stdout directly in case of an interactive command
|
|
line interface (like printing errors for command line arguments).
|
|
|
|
Ordering of #include directives:
|
|
1) The interface that the current file implements, ""
|
|
2) Internal interfaces, from core-ish to utility-ish, ""
|
|
3) Bundled libraries, <>
|
|
4) Installed libraries, <>
|
|
5) STL headers, <>
|
|
6) System headers, <>
|
|
|
|
Exceptions
|
|
----------
|
|
Do not use assert(); throw anonymous exceptions instead:
|
|
- if(fail) throw Exception("Thing failed");
|
|
|
|
In normal operation, zero exceptions should be thrown. Unless any potential bugs
|
|
are occurring, you should be able to play the game fine if you set a breakpoint
|
|
on a GCC Linux build to __cxa_throw, which will stop the program immediately
|
|
when an exception occurs.
|
|
|
|
Exceptions are allowed to occur when a resource has expired that the caller had
|
|
to expect to still be valid in order to avoid some kind of ridiculous code
|
|
structure.
|
|
|
|
Non-exception throwing and exception-throwing methods
|
|
-----------------------------------------------------
|
|
- get_x: Returns nullptr or equivalent if not found
|
|
- find_x: Returns nullptr or equivalent if not found
|
|
- check_x: Throws NullptrCatch if not found
|
|
|
|
To check for nullptr returned by get_x() or find_x(), use the check() function
|
|
in core/types.h.
|
|
|
|
Threads
|
|
-------
|
|
The program should always be debuggable with Helgrind and DRD, without false
|
|
positives.
|
|
|
|
Only use synchronization primitives that wrap pthreads, because that is what
|
|
Helgrind and DRD support.
|
|
|
|
If an object owns a thread, the thread should not be stopped in the object's
|
|
destructor. Instead the object should have thread_request_stop() and
|
|
thread_join() methods which should always be called before the object is
|
|
destructed. This allows fast parallel shutdown and better control over
|
|
destruction. You can skip this if you somehow can do it without Hellgrind and
|
|
DRD bitching at you though.
|
|
|
|
Directory structure
|
|
-------------------
|
|
├── 3rdparty << Bundled 3rd-party libraries
|
|
├── Build << Build files; "mkdir Build; cmake ..; make"
|
|
├── cache << Runtime directory used by Buildat
|
|
├── builtin << Built-in modules
|
|
├── client << Built-in client files
|
|
├── extensions << Built-in client extensions
|
|
├── src
|
|
│ ├── client << Client-specific code
|
|
│ ├── core << Core code (must be kept minimal but sufficient)
|
|
│ ├── impl << Interface implementations
|
|
│ ├── interface << Interface available to modules
|
|
│ └── server << Server-specific code
|
|
├── games << Games that can be run using buildat_server -m <path>
|
|
└── util << Miscellaneous development utilities
|
|
|
|
Commit messages
|
|
---------------
|
|
Commit messages must be formatted in the following way:
|
|
|
|
In present tense. Prepend a location to the message where possible. When adding
|
|
something, the "add" verb should be left out. Fine enough examples:
|
|
- client/sandbox.lua: Fix string concatenation when creating an error message
|
|
- interface::Server::check_module
|
|
- doc: conventions.txt, todo.txt
|
|
- Remove Module::test_add
|
|
- client, 3rdparty/c55lib: Command-line parameters
|
|
- 3rdparty/cereal
|
|
- client: Disable Urho3D log file
|
|
- extensions/__menu: Fix UI warnings
|
|
|
|
Urho3D
|
|
------
|
|
Urho3D's namespace should generally be aliased to be "magic".
|
|
|