Tech/LxEngine/Coding Style

Principles

 * Clarity of code should be foremost; only sacrifice for efficiency in proven bottlenecks
 * Prefer concise and clear over general and flexible
 * Prefer free-standing functions to class methods
 * Use "::detail" sub-namespace to hide implementation details that client code should not need to be aware of
 * Avoid implicit operations: implicit casts, implicit single-parameter constructors, etc.
 * Reduce dependencies
 * Consistency
 * Reduce the number of concepts
 * Use standard, familiar concepts, patterns, paradigms, and names
 * Reduce special cases and details
 * Comment extensively; comment on the higher-level intent of the code not a literal transcription of what the code does

If it's complicated, it's not done yet - That's a good principle for the code. It's alright for a first revision of some code to be a bit complex because it takes work to make things simple. The key idea to remember is that the code is not done when it 'works'; it needs to be iterated over until it is simple.

Conventions

 * ClassPtr = std::shared_ptr
 * ClassCPtr = std::shared_ptr
 * ClassWPtr = std::weak_ptr
 * ClassCWPtr = std::weak_ptr
 * kVarName = constant value
 * eVarName = enumeration value
 * g_varName = global scope variable
 * s_varName = static scope variable
 * mVarName = member variable
 * spVarName = smart-pointer to variable
 * wpVarName = weak-pointer to variable
 * pVarName = raw pointer to variable
 * _methodName = intended for internal use only, usually protected methods
 * 'internal:: = sub-namespace for internal use only classes
 * detail:: = sub-namespace for implementation details that rarely relevant to the client
 * #include <../detail/file.hpp> = header for internal use only


 * Line length: lines, from their start (which likely is not column 0), should be 80 characters (preferable) to ~120 (when necessary)

Classes and Concepts
LxEngine developers should be familiar with the following classes and concepts and, for consistency, use them when appropriate (rather than alternate implementations):


 * lambda functions
 * auto keyword
 * std::function<>
 * std::vector<>
 * std::map<>
 * std::shared_ptr<>
 * std::weak_ptr<>
 * std::unique_ptr<>
 * boost::format<>
 * boost::any<>
 * boost::algorithm::string
 * HTML DOM
 * Javascript
 * JSON data
 * GLM library

Todos
Ideally todos should be in the following format:

There are four parts to the above:
 * The stub method / class / section of code that defines exactly where the to-be-implemented code should go.  Don't necessarily enforce a design on the implementation, but do provide the location where that implementation will be written or called from.  The more descriptive a name that can be assigned to the stub method, the better.
 * The Doxygen todo comment provides a short summary for developers looking for tasks
 * The full description provides a valuable description. It is essential to write this rather than simply leaving a vague todo.  At the time the todo is being written, the developer has a great deal of useful information for a future developer (even himself) in the context of the work being done.  This section can be written as quickly and roughly as necessary, but should provide as much information as possible on what specifically needs to be done.
 * The error: this provides the runtime notification that an incomplete part of the system has been invoked. In some cases, a warning may be acceptable if the todo is truly supplemental and not essential functionality

Glossary

 * ensure - uses to prefix a method or function on a cached resource or state change that, if the resource is ready or the state already set will do minimal work, otherwise it will set that state or ready that resource

Use size_t or int for values that shouldn't ever negative?
Example: should Image::width return a size_t or an int?

Response: