buildat/doc/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 based on Uncrustify. (http://uncrustify.sourceforge.net/)
Always run before committing. It handles most whitespace issues.

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

Do not use assert(); throw anonymous exceptions instead:
- if(fail) throw Exception("Thing failed");

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, <>

Non-exception throwing and exception-throwing methods
-----------------------------------------------------
- get_x: Returns NULL or equivalent if not found
- check_x: Throws exception if not found

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