dinit/doc/CODE-STYLE

Code style in Dinit
===================

This document presents a brief overview of the style used in the Dinit source code. It may not be
exhaustive. If you would like to contribute, please check this guide and also observe any existing
code style.

1. Line widths - do not exceed 110 characters; try to limit to 100. When wrapping a line, the
   indent should be increased by at least two levels on the subsequent lines.

2. Curly braces - for classes and functions, the opening brace appears by itself on an empty line,
   as does the closing brace. In other cases the opening brace should appear at the end of the
   line (and not on a line by itself). The closing brace always appears on a line by itself.

   If curly braces are omitted (for a control statement) then the entire statement should be a
   single line. Otherwise the braces are mandatory.

       class a
       {
           void foo()
           {
               if (true) {
                   // ok - braces used
               }

               if (true) foo(); // ok - same line
           }
       }

   2.1. Else - "else" follows the closing brace of the associated "if". Rules for braces are the
        same as for "if".

   2.2. Omit "else" if the body of the associated "if" does not fall through (i.e. if it always
        either returns or throws an exception).

3. Indentation - is 4 spaces per level. Never tabs. Indentation level increases after an opening
   curly brace, though for long namespace declarations this is optional.

4. Blank lines - should be used between method and class definitions, and can be used in code
   to break it into sections with different concerns. A double blank line should never appear
   inside a function, and generally not inside a class, but may be used to indicate a significant
   break. Blank lines should never immediately follow an opening curly brace nor precede a
   closing curly brace.

5. Exceptions - should be used sparingly. Much of the Dinit code is exception-free and this
   needs to be maintained. Functions that cannot throw or propagate exceptions should be marked
   as "noexcept".

   5.1 Avoid using exceptions for normal control flow. That is, exceptions should generally be
       considered hard errors.

6. Pointers and references - the rules are a bit loose here, but in general function parameters
   which may be modified by the callee should be passed via pointer, to act as a visual aid
   in understanding the function semantics.

7. Balance maintainability (including readability) with efficiency. Existing code should serve
   as a guide.

8. Comments for a class should precede the class (with no intervening blank lines). Similarly for
   a function. Member functions should be commented at the declaration (i.e. in the header file
   rather than the source file).

   8.1. Use "TODO" to indicate a desirable future improvement. This should be used minimally; in
        general, it is better to do the thing than to comment that the thing should be done.

   8.2. Use complete sentences/paragraphs and avoid uncommon abbreviations. Do not drop articles
        ("the", "a", "an").

   8.3 Comment structure for functions: short description, parameters, return value, and any
       exceptions that may be thrown (with reason the exception may be thrown, if it is not
       implicit in the type). Any longer/detailed notes can follow after the above.
       
       Example:
       
       // Add a dependency. Caller must ensure that the services are in an appropriate state and
       // that a circular dependency chain is not created. Propagation queues should be processed
       // after calling this (if dependency may be required to start).
       // Parameters:
       //   to - target of dependency to be added
       //   dep_type - the type of the dependency
       //   i - where to insert the dependency (in dependencies list)
       // Returns:
       //   A reference to the dependency just added
       // Throws:
       //   std::bad_alloc