Coding Conventions

This page summarizes the coding conventions used for RST.

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 <file name w/o ext>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:

1. package declaration on first line
2. import statements
3. option statements
4. Message definitions