.. _conventions: ==================== Coding Conventions ==================== This page summarizes the coding conventions used for |project|. Generally, data types are declared using the `Google Protocol Buffers`_ IDL syntax and hence the proposed conventions for this language apply. They can be found in the `Google Protocol Buffers Style Guide `_. Apart from the general conventions we apply the following ones: .. note:: The source code is continuously checked against these conventions using the CI server. Results of the checks can be found at: https://ci.cor-lab.org/view/rst/job/rst-trunk-static-analysis/ Naming ====== * Do not include artifacts of the current communication pattern for one type. I.e. if you currently send events of images, your type must not be ``ImageEvent``, but solely ``Image``, as the ``Image`` type might later be reused in an RPC communication. * The `Google Protocol Buffers`_ option ``java_outer_class_name`` is always specified using the pattern ``Type``. Directory and File Layout ========================= * The directory (relative to the ``proto/{stable,sandbox}`` directory in the project root) in which the proto-file resides must match the package name with all "."s replaced with "/"s. * The filename must match the name of the "primary" message definition (with ".proto" appended). * There should only be one "primary" message definition in each proto-file. * Groups of related messages should reside in individual files and refer to each other using the ``import`` directive. * Directory names are all lowercase and without word separations, e.g. ``imageprocessing``. * ``imports`` are always performed using absolute paths starting from the ``rst`` package, e.g. ``import "rst/vision/Image.proto";``. Rationale --------- * Facilitate easy documentation and reuse via ``import``. * Data definitions can be treated as resources with unique URLs in e.g. a repository browser. Example ------- In case you have define a type with the name ``MyTestType`` which logically belongs to the ``foo`` domain, the containing file needs to declare ``package rst.foo;`` in the first line and must reside in the project folder ``proto/{stable,sandbox}/rst/foo`` with the name ``MyTestType.proto``. Indentation and White Spaces ============================ * Indentation is performed exclusively using spaces. No tabs! * Indentations are always multiples of 4 spaces. * All lines must not have trailing spaces. * There is always a newline at the end of file * File-wide declarations like ``package``, ``import`` or ``option`` statements must not be indented. * All definitions inside ``message`` and ``enum`` definitions are indented by 4 spaces. * Curly braces are placed on the same lines as ``message`` or ``enum`` definitions. The closing curly brace is on a new line. * All elements are at a maximum separated by one empty line. File Content Structure ====================== Each file is constructed as follows: #. ``package`` declaration on first line #. ``import`` statements #. ``option`` statements #. Message definitions