From edde29e203fbdd2cbf22abb1bf667d069786af14 Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Tue, 4 Dec 2018 05:10:47 +0530 Subject: coding-naming: Convert TBD to Rest format (GCI 2018) --- eng/coding-naming.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 2 deletions(-) (limited to 'eng') diff --git a/eng/coding-naming.rst b/eng/coding-naming.rst index 054dd5d..4fb4e7c 100644 --- a/eng/coding-naming.rst +++ b/eng/coding-naming.rst @@ -6,5 +6,88 @@ Naming Rules ************ -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/NamingRules +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/NamingRules + +General Rules +------------- + + * Avoid abbreviations. + + * Exception: when the abbreviation is more common than the full word. + * Exception: For well-known acronyms. + + * Use descriptive language. + * File names should be lower-case alphabet letters only, plus the extension. + Avoid symbols in file names. + * Prefer to use underscores to separate words, rather than + `CamelCase `_.or !TitleCase. + * Local-scope variable names are all lower case with underscores between words. + * CPP macros are all capital letters with underscores between words. + * Enumerated (enum) values are all capital letters with underscores between + words, but the type name follows the regular rules of other type names. + * Constant (const) variables follow the same rules as other variables. + An exception is that a const that replaces a CPP macro might be all + capital letters for backward compatibility. + * Type names, function names, and global scope names have different rules + depending on whether they are part of the public API or are internal + to RTEMS, see below. + +**User-Facing APIs** + +The public API routines follow a standard API like POSIX or BSD or start +with *rtems_*. If a name starts with *rtems_*, then it should be assumed to be +available for use by the application and be documented in the User's Guide. + +If the method is intended to be private, then make it static to a file or +start the name with a leading _. + +**Classic API** + +* Public facing APIs start with *rtems_* followed by a word or phrase to + indicate the Manager or functional category the method or data type + belongs to. + +* Non-public APIs should be static or begin with a leading _. The required + form is the use of a leading underscore, functional area with leading + capital letter, an underscore, and the method with a leading capital letter. + +**POSIX API** + + * Follow the rules of POSIX. + +**RTEMS Internal Interfaces** + +**Super Core** + +The `Super Core `_. is organized in an +Object-Oriented fashion. Each score Handler is a Package, or Module, +and each Module contains type definitions, functions, etc. +The following summarizes our conventions for using names within +`SuperCore `_. Modules. + + * Use "Module_name_Particular_type_name" for type names. + * Use "_Module_name_Particular_function_name" for functions names. + * Use "_Module_name_Global_or_file_scope_variable_name" for global or + file scope variable names. + +Within a structure: + + * Use "Name" for struct aggregate members. + * Use "name" for reference members. + * Use "name" for primitive type members. + +As shown in the following example: + + .. code-block:: c + + typedef struct { + Other_module_Struct_type Aggregate_member_name; + Other_module_Struct_type *reference_member_name; + Other_module_Primitive_type primitive_member_name; + } The_module_Type_name; + + +**BSP** + + * TODO. -- cgit v1.2.3