source: rtems-docs/eng/coding-naming.rst @ 1fdd3cf

5
Last change on this file since 1fdd3cf was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

  • Property mode set to 100644
File size: 3.3 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2018.
4.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
5
6Naming 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
12General 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
38The public API routines follow a standard API like POSIX or BSD or start
39with *rtems_*. If a name starts with *rtems_*, then it should be assumed to be
40available for use by the application and be documented in the User's Guide.
41
42If the method is intended to be private, then make it static to a file or
43start 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
63The `Super Core <https://docs.rtems.org/doxygen/cpukit/html/>`_. is organized in an
64Object-Oriented fashion. Each score Handler is a Package, or Module,
65and each Module contains type definitions, functions, etc.
66The 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
74Within a structure:
75
76 *  Use "Name" for struct aggregate members.
77 *  Use "name" for reference members.
78 *  Use "name" for primitive type members.
79
80As 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.
Note: See TracBrowser for help on using the repository browser.