2.1. General Rules

The following rules generally apply and follow the naming schema GENERAL:<ongoing-number>.

2.1.1. Filenames (GENERAL:001)

Generally file naming rules are not necessary, but for reasons of consistency there are some rules for that within the project.

Filenames

Filenames as well as directory names SHOULD only consist of lowercase alphanumeric characters and may include underscores (_), dashes (-) and dots (.). A correct file or directory name matches the regular expression ^[a-z0-9_\-.]*$. Valid exceptions are e.g., README.md and CHANGELOG.md.

2.1.2. Filename uniqueness (GENERAL:002)

Unique filenames help to avoid confusion. Furthermore in case of file includes or imports non-unique filenames might lead to undesired behavior as wrong files might be used.

Filename Uniqueness

  • Filenames SHOULD BE be unique. Valid exceptions are e.g., README.md to explain the content of a directory, or directory-local .gitignore files.

  • Source files MUST use unique filenames.

2.1.3. Encoding (GENERAL:003)

Encoding

  • All plain text files SHOULD use UTF-8 encoding.

  • Files MAY use other encodings if these are required by standards or other tools. Valid exceptions are

    • *.c* and *.h files MUST use ASCII encoding

    • *.sym and *.dbc files MUST use ASCII encoding.

2.1.4. End-of-File (GENERAL:004)

End of File

All plain text files MUST end with a single empty line (POSIX, 3.206 Line).

2.1.5. No trailing whitespace (GENERAL:005)

Undesired changes in whitespace make diffs more hard to read and are unnecessary. To reduce this problem, trailing whitespace is not allowed.

No trailing whitespace

All plain text files MUST NOT add trailing whitespace.

2.1.6. Indentation (GENERAL:006)

Undesired changes in whitespace make diffs more hard to read and are unnecessary. To reduce this problem, all indentations MUST be of one type.

Indentation

  • All plain text files MUST use spaces for indentation. Use 4 spaces at a time.

  • Tabs MUST NOT be used.

You should set your editor to automatically replace tabs with spaces to ease development.

2.1.7. Further General Rules

  • Optimize for readability using descriptive names that would be clear even to people on a different team.

  • Use names that describe the purpose or intent of the object. Do not worry about saving horizontal space as it is far more important to make your code immediately understandable to a new reader. Minimize the use of abbreviations that would likely be unknown to someone outside your project (especially acronyms and initialisms). Do not abbreviate by deleting letters within a word. As a rule of thumb, an abbreviation is probably ok if it’s listed in Wikipedia. Generally speaking, descriptiveness should be proportional to the name’s scope of visibility. For example, n may be a fine name within a 5-line function, but within the scope of a file, it’s likely too vague.

  • For the purposes of the naming rules below, a “word” is anything that you would write in English without internal spaces. This includes abbreviations and acronyms; e.g., for “camel case” or “Pascal case,” in which the first letter of each word is capitalized, use a name like StartRpc(), not StartRPC().

  • Non-ASCII characters should be rare, and MUST use UTF-8 encoding. You SHOULD NOT hard-code user-facing text in source code, even English, so use of non-ASCII characters should be rare. However, in certain cases it is appropriate to include such words in your code. For example, if your code parses data files from foreign sources, it may be appropriate to hard-code the non-ASCII string(s) used in those data files as delimiters. More commonly, unit test code (which does not need to be localized) might contain non-ASCII strings. In such cases, you should use UTF-8, since that is an encoding understood by most tools able to handle more than just ASCII. Hex encoding is also ok, and encouraged where it enhances readability - for example, “\xEF\xBB\xBF”, or, even more simply, u8”\uFEFF”, is the Unicode zero-width no-break space character, which would be invisible if included in the source as straight UTF-8.

  • When referring to files inside the repository the UNIX-style path separator MUST be used. When referring to files outside the repository the platform specific path separator MUST be used (e.g., src/app/main/main.c and C:\Users\vulpes).

  • References to functions should be kept as simple and maintainable as possible. For example when referring to a function with the declaration uint8_t ABC_MyFunction(uint8_t a, bool b) the reference SHOULD only use ABC_MyFunction() without arguments or ellipses. If the context requires specific arguments they MAY be provided. The ellipses form MUST NOT be used (see https://en.wikipedia.org/wiki/Ellipsis), e.g., do not use ABC_MyFunction(...)).