2
0

CODE-STYLE 3.9 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
  1. Code style in Dinit
  2. ===================
  3. This document presents a brief overview of the style used in the Dinit source code. It may not be
  4. exhaustive. If you would like to contribute, please check this guide and also observe any existing
  5. code style.
  6. 1. Line widths - do not exceed 110 characters; try to limit to 100. When wrapping a line, the
  7. indent should be increased by at least two levels on the subsequent lines.
  8. 2. Curly braces - for classes and functions, the opening brace appears by itself on an empty line,
  9. as does the closing brace. In other cases the opening brace should appear at the end of the
  10. line (and not on a line by itself). The closing brace always appears on a line by itself.
  11. If curly braces are omitted (for a control statement) then the entire statement should be a
  12. single line. Otherwise the braces are mandatory.
  13. class a
  14. {
  15. void foo()
  16. {
  17. if (true) {
  18. // ok - braces used
  19. }
  20. if (true) foo(); // ok - same line
  21. }
  22. }
  23. 2.1. Else - "else" follows the closing brace of the associated "if". Rules for braces are the
  24. same as for "if".
  25. 2.2. Omit "else" if the body of the associated "if" does not fall through (i.e. if it always
  26. either returns or throws an exception).
  27. 3. Indentation - is 4 spaces per level. Never tabs. Indentation level increases after an opening
  28. curly brace, though for long namespace declarations this is optional.
  29. 4. Blank lines - should be used between method and class definitions, and can be used in code
  30. to break it into sections with different concerns. A double blank line should never appear
  31. inside a function, and generally not inside a class, but may be used to indicate a significant
  32. break. Blank lines should never immediately follow an opening curly brace nor precede a
  33. closing curly brace.
  34. 5. Exceptions - should be used sparingly. Much of the Dinit code is exception-free and this
  35. needs to be maintained. Functions that cannot throw or propagate exceptions should be marked
  36. as "noexcept".
  37. 5.1 Avoid using exceptions for normal control flow. That is, exceptions should generally be
  38. considered hard errors.
  39. 6. Pointers and references - the rules are a bit loose here, but in general function parameters
  40. which may be modified by the callee should be passed via pointer, to act as a visual aid
  41. in understanding the function semantics.
  42. 7. Balance maintainability (including readability) with efficiency. Existing code should serve
  43. as a guide.
  44. 8. Comments for a class should precede the class (with no intervening blank lines). Similarly for
  45. a function. Member functions should be commented at the declaration (i.e. in the header file
  46. rather than the source file).
  47. 8.1. Use "TODO" to indicate a desirable future improvement. This should be used minimally; in
  48. general, it is better to do the thing than to comment that the thing should be done.
  49. 8.2. Use complete sentences/paragraphs and avoid uncommon abbreviations. Do not drop articles
  50. ("the", "a", "an").
  51. 8.3 Comment structure for functions: short description, parameters, return value, and any
  52. exceptions that may be thrown (with reason the exception may be thrown, if it is not
  53. implicit in the type). Any longer/detailed notes can follow after the above.
  54. Example:
  55. // Add a dependency. Caller must ensure that the services are in an appropriate state and
  56. // that a circular dependency chain is not created. Propagation queues should be processed
  57. // after calling this (if dependency may be required to start).
  58. // Parameters:
  59. // to - target of dependency to be added
  60. // dep_type - the type of the dependency
  61. // i - where to insert the dependency (in dependencies list)
  62. // Returns:
  63. // A reference to the dependency just added
  64. // Throws:
  65. // std::bad_alloc