Skip to content

Latest commit

 

History

History
44 lines (35 loc) · 2.12 KB

HACKING.md

File metadata and controls

44 lines (35 loc) · 2.12 KB
Raw

Important notes on the code

You can generate an internal overview with doxygen. For this, use make doc-doxygen and you'll find an internal overview of all functions and symbols in docs/internal/html.

Comments

  • Comment system is held similar to JavaDoc
    • Use @param to describe all input parameters
    • Documentation comments should start with a double star (/**)
    • Append () to function names and prepend variables with # to properly reference them in the docs
  • Add comments to all functions and methods
  • Markdown inside the comments is allowed and also desired
  • Add the comments to the prototype. Doxygen will merge the protoype and implementation documentation anyways. Except for static methods, add the documentation header to the implementation and not to the prototype.
  • Member documentation should happen with /**< and should span to the right side of the member

Log messages

Messages

  • Keep your message in common format: <problem>: <problematic value/description>
  • If you have to write text, single quote values in your sentence.

Levels

For logging, there are printf-like macros LOG_(E|C|W|M|I|D).

  • LOG_E (ERROR):
    • All messages, which lead to immediate abort and are caused by a programming error. The program needs patching and the error is not user recoverable.
    • e.g.: Switching over an enum, LOG_E would go into the default case.
  • LOG_C (CRITICAL):
    • The program cannot continue to work. It is used in the wrong manner or some outer conditions are not met.
    • e.g.: -config parameter value is unreadable file
  • LOG_W (WARNING):
    • Something is not in shape, but it's recoverable.
    • e.g.: A value is not parsable in the config file, which will default.
  • LOG_M (MESSAGE):
    • Important info, which informs about the state.
    • e.g.: An empty notification does get removed immediately.
  • LOG_I (INFO):
    • Mostly unneccessary info, but important to debug (as the user) some use cases.
    • e.g.: print the notification contents after arriving
  • LOG_D (DEBUG):
    • Only important during development or tracing some bugs (as the developer).