.. include:: ./../../macros.txt .. include:: ./../../units.txt .. _GENERAL_RULES: General Rules ============= The following rules generally apply and follow the naming schema ``GENERAL:``. .. _rule_general_filenames: Filenames (``GENERAL:001``) --------------------------- Generally file naming rules are not necessary, but for reasons of consistency there are some rules for that within the project. .. admonition:: 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``. .. _rule_general_filename_uniqueness: 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. .. admonition:: 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. .. _rule_general_text_file_encoding: Encoding (``GENERAL:003``) -------------------------- .. admonition:: 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. .. _rule_general_eof: End-of-File (``GENERAL:004``) ----------------------------- .. admonition:: End of File All plain text files **MUST** end with a single empty line (`POSIX, 3.206 Line `_). .. _rule_general_no_trailing_whitespace: 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. .. admonition:: No trailing whitespace All plain text files **MUST NOT** add trailing whitespace. .. _rule_general_indentation: 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. .. admonition:: 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. .. _further_general_rules: 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 ``StartAbc()``, not ``StartABC()``. - 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(...)``.