1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2018. |
---|
4 | .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project |
---|
5 | |
---|
6 | Naming Rules |
---|
7 | ************ |
---|
8 | |
---|
9 | .. COMMENT:TBD - Convert the following to Rest and insert into this file |
---|
10 | .. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/NamingRules |
---|
11 | |
---|
12 | General Rules |
---|
13 | ------------- |
---|
14 | |
---|
15 | * Avoid abbreviations. |
---|
16 | |
---|
17 | * Exception: when the abbreviation is more common than the full word. |
---|
18 | * Exception: For well-known acronyms. |
---|
19 | |
---|
20 | * Use descriptive language. |
---|
21 | * File names should be lower-case alphabet letters only, plus the extension. |
---|
22 | Avoid symbols in file names. |
---|
23 | * Prefer to use underscores to separate words, rather than |
---|
24 | `CamelCase <https://devel.rtems.org/wiki/CamelCase>`_.or !TitleCase. |
---|
25 | * Local-scope variable names are all lower case with underscores between words. |
---|
26 | * CPP macros are all capital letters with underscores between words. |
---|
27 | * Enumerated (enum) values are all capital letters with underscores between |
---|
28 | words, but the type name follows the regular rules of other type names. |
---|
29 | * Constant (const) variables follow the same rules as other variables. |
---|
30 | An exception is that a const that replaces a CPP macro might be all |
---|
31 | capital letters for backward compatibility. |
---|
32 | * Type names, function names, and global scope names have different rules |
---|
33 | depending on whether they are part of the public API or are internal |
---|
34 | to RTEMS, see below. |
---|
35 | |
---|
36 | **User-Facing APIs** |
---|
37 | |
---|
38 | The public API routines follow a standard API like POSIX or BSD or start |
---|
39 | with *rtems_*. If a name starts with *rtems_*, then it should be assumed to be |
---|
40 | available for use by the application and be documented in the User's Guide. |
---|
41 | |
---|
42 | If the method is intended to be private, then make it static to a file or |
---|
43 | start the name with a leading _. |
---|
44 | |
---|
45 | **Classic API** |
---|
46 | |
---|
47 | * Public facing APIs start with *rtems_* followed by a word or phrase to |
---|
48 | indicate the Manager or functional category the method or data type |
---|
49 | belongs to. |
---|
50 | |
---|
51 | * Non-public APIs should be static or begin with a leading _. The required |
---|
52 | form is the use of a leading underscore, functional area with leading |
---|
53 | capital letter, an underscore, and the method with a leading capital letter. |
---|
54 | |
---|
55 | **POSIX API** |
---|
56 | |
---|
57 | * Follow the rules of POSIX. |
---|
58 | |
---|
59 | **RTEMS Internal Interfaces** |
---|
60 | |
---|
61 | **Super Core** |
---|
62 | |
---|
63 | The `Super Core <https://docs.rtems.org/doxygen/cpukit/html/>`_. is organized in an |
---|
64 | Object-Oriented fashion. Each score Handler is a Package, or Module, |
---|
65 | and each Module contains type definitions, functions, etc. |
---|
66 | The following summarizes our conventions for using names within |
---|
67 | `SuperCore <https://docs.rtems.org/doxygen/cpukit/html/>`_. Modules. |
---|
68 | |
---|
69 | * Use "Module_name_Particular_type_name" for type names. |
---|
70 | * Use "_Module_name_Particular_function_name" for functions names. |
---|
71 | * Use "_Module_name_Global_or_file_scope_variable_name" for global or |
---|
72 | file scope variable names. |
---|
73 | |
---|
74 | Within a structure: |
---|
75 | |
---|
76 | * Use "Name" for struct aggregate members. |
---|
77 | * Use "name" for reference members. |
---|
78 | * Use "name" for primitive type members. |
---|
79 | |
---|
80 | As shown in the following example: |
---|
81 | |
---|
82 | .. code-block:: c |
---|
83 | |
---|
84 | typedef struct { |
---|
85 | Other_module_Struct_type Aggregate_member_name; |
---|
86 | Other_module_Struct_type *reference_member_name; |
---|
87 | Other_module_Primitive_type primitive_member_name; |
---|
88 | } The_module_Type_name; |
---|
89 | |
---|
90 | |
---|
91 | **BSP** |
---|
92 | |
---|
93 | * TODO. |
---|