9. Naming Conventions

9.1 Type-Based Naming Conventions

Names may be constrained by the scope of the name (external, file static, internal), the file in which the identifier is defined, the type of the identifier, and global constraints.

9.1.1 Czech Names

Of course, this is a complete jumble to the uninitiated, and that's the joke.
- Charles Simonyi, on the Hungarian naming convention

Czech[23] names denote operations and variables of abstract types by preceding the names by <type>_. The remainder of the name should begin with a lowercase character, but may use any other character besides the underscore. Types may be named using any non-underscore characters.

The Czech naming convention is selected by the czech flag. If accessczech is on, a function, variable, constant or iterator named <type>_<name> has access to the abstract type <type>.

Reporting of violations of the Czech naming convention is controlled by different flags depending on what is being declared:

czechfcns

Functions and iterators. An error is reported for a function name of the form <prefix>_<name> where <prefix> is not the name of an accessible type. Note that if accessczech is on, a type named <prefix> would be accessible in a function beginning with <prefix>_. If accessczech is off, an error is reported instead. An error is reported for a function name that does not have an underscore if any abstract types are accessible where the function is defined.

Variables, constants and expanded macros. An error is reported if the identifier name starts with <prefix>_ and prefix is not the name of an accessible abstract type, or if an abstract type is accessible and the identifier name does not begin with <type>_ where type is the name of an accessible abstract type. If accessczech is on, the representation of the type is visible in the constant or variable definition.

User-defined types. An error is reported if a type name includes an underscore character.

9.1.2 Slovak Names

The slovak flag selects the Slovak naming convention. Like Czech names, it may be used with accessslovak to control access to abstract representations. The slovakfcns, slovakvars, slovakconstants, and slovakmacros flags are analogous to the similar Czech flags. If slovaktype is on, an error is reported if a type name includes an uppercase letter.

9.1.3 Czechoslovak Names

9.2 Namespace Prefixes

All namespace flags are of the form, -<context>prefix <string>. For example, the macro variable namespace restricting identifiers declared in macro bodies to be preceded by "m_" would be selected by -macrovarprefix "m_". The string may contain regular characters that may appear in a C identifier. These must match the initial characters of the identifier name. In addition, special characters (shown in Table 1) can be used to denoted a class of characters.[24] The * character may be used at the end of a prefix string to specify the rest of the identifier is zero or more characters matching the character immediately before the *. For example, the prefix string "T&*" matches "T" or "TWINDOW" but not "Twin".

^    Any uppercase letter, A-Z                                                 
&    Any lowercase letter, a-z                                                 
%    Any character that is not an uppercase letter (allows lowercase           
     letters, digits and underscore)                                           
~    Any character that is not a lowercase letter (allows uppercase letters,   
     digits and underscore)                                                    
$    Any letter (a-z, A-Z)                                                     
/    Any letter or digit (A-Z, a-z, 0-9)                                       
?    Any character valid in a C identifier                                     
#    Any digit, 0-9                                                            

Different prefixes can be selected for the following identifier contexts:

macrovarprefix

Any variable declared inside a macro body

Any macro that is not checked as a function or constant (see Section 8.4)

Tags for struct, union and enum declarations

Members of enum types

Name of a user-defined type

Any identifier with file static scope

Any variable (not of function type) with global variables scope

Any exported identifier

If an identifier is in more than one of the namespace contexts, the most specific defined namespace prefix is used (e.g., a global variable is also an exported identifier, so if globalvarprefix is set, it is checked against the variable name; if not, the identifier is checked against the externalprefix.)

For each prefix flag, a corresponding flag named <prefixname>exclude controls whether errors are reported if identifiers in a different namespace match the namespace prefix. For example, if macrovarprefixexclude is on, LCLint checks that no identifier that is not a variable declared inside a macro body uses the macro variable prefix.

Here is a (somewhat draconian) sample naming convention:

-uncheckedmacroprefix "~*"
unchecked macros have no lowercase letters
-typeprefix "T^&*"
all type typenames begin with T followed by an uppercase letter. The rest of the name is all lowercase letters.
+typeprefixexclude
no identifier that does not name a user-defined type may begin with the type name prefix (set above)
-filestaticprefix"^&&&"
file static scope variables begin with an uppercase letter and three lowercase letters
-globvarprefix "G"
all global variables variables start with G
+globvarprefixexclude
no identifier that is not a global variable starts with G

9.3 Naming Restrictions

9.3.1 Reserved Names

9.3.2 Distinct Identifiers

The decision to retain the old six-character case-insensitive restriction on significance was most painful.
- ANSI C Rationale

LCLint can check that identifiers differ within a given number of characters, optionally ignoring alphabetic case and differences between characters that look similar. The number of significant characters may be different for external and internal names.

Using +distinctexternalnames sets the number of significant characters for external names to six and makes alphabetical case insignificant for external names. This is the minimum significance acceptable in an ANSI-conforming compiler. Most modern compilers exceed these minimums (which are particularly hard to follow if one uses the Czech or Slovak naming convention). The number of significant characters can be changed using the externalnamelength <number> flag. If externalnamecaseinsensitive is on, alphabetical case is ignored in comparing external names. LCLint reports identifiers that differ only in alphabetic case.

For internal identifiers, a conforming compiler must recognize at least 31 characters and treat alphabetical cases distinctly. Nevertheless, it may still be useful to check that internal names are more distinct then required by the compiler to minimize the likelihood that identifiers are confused in the program. Analogously to external names, the internalnamelength <number> flag sets the number of significant characters in an internal name and internalnamecaseinsensitive sets the case sensitivity. The internalnamelookalike flag further restricts distinctions between identifiers. When set, similar-looking characters match -- the lowercase letter "l" matches the uppercase letter "I" and the number "1"; the letter "O" or "o" matches the number "0"; "5" matches "S"; and "2" matches "Z". Identifiers that are not distinct except for look-alike characters will produce an error message. External names are also internal names, so they must satisfy both the external and internal distinct identifier checks.

Figure 18 illustrates some of the name checking done by LCLint.