Coding Conventions
This page summarizes the coding conventions used for RST.
Generally, data types 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.
Apart from the general conventions we apply the following ones:
Naming
- Do not include a description of a particular communication pattern
in the name of a data type. For example, if you currently
send events containing images, your 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
TYPE-NAMEType. 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.
- 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 type definitions can be treated as resources with
unique URLs in e.g. a repository browser.
Example
In case you define a 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 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.