.. _conventions:

====================
 Coding Conventions
====================

This page summarizes the coding conventions used for |project|.

Generally, :term:`data types <data type>` are described 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
<https://developers.google.com/protocol-buffers/docs/style>`_.

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 a description of a particular communication pattern
  in the name of a :term:`data type`. For example, if you currently
  send events containing images, your :term:`data type` must not be
  called ``ImageEvent``, but ``Image``, as the name ``Image`` would
  also be suitable for other patterns like RPC communication.

* The `Google Protocol Buffers`_ option ``java_outer_class_name`` has
  to specified and its value has to be of the form
  :samp:`{TYPE-NAME}Type`. For example, the correct value for
  ``Image`` is ``ImageType``.

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``.

* ``import``\ s 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``.

* :term:`Data type` definitions can be treated as resources with
  unique URLs in e.g. a repository browser.

Example
-------

In case you define a :term:`data type` named ``MyData`` which
logically belongs to the ``foo`` package, the containing file has to
contain the package declaration ``package rst.foo;`` in the first line
and must reside in the directory ``proto/{stable,sandbox}/rst/foo``
with the name :file:`MyData.proto`.

File Content Structure
======================

Each file is constructed as follows:

#. ``package`` declaration on first line

#. ``import`` statement(s)

#. ``option`` statement(s)

#. Message definition(s)

Indentation and White Spaces
============================

* Indentation is performed exclusively using spaces (not tabs).

* Indentations are always multiples of 4 spaces.

* There must be no have trailing spaces.

* Each file ends with a newline.

* File-wide declarations like ``package``, ``import`` or ``option``
  statements must not be indented.

* All text inside ``message`` and ``enum`` definitions are indented by
  4 spaces.

* Curly braces are placed on the same lines as the corresponding
  ``message`` or ``enum`` keywords. The closing curly brace is on a
  separate line.

* All elements are at a maximum separated by one empty line.