conventions.txt

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".