11.4. Informal Naming Conventions
| < Free Open Study > |
| Most projects use relatively informal naming conventions such as the ones laid out in this section. Guidelines for a Language-Independent ConventionHere are some guidelines for creating a language-independent convention: Differentiate between variable names and routine names The convention this book uses is to begin variable and object names with lower case and routine names with upper case: variableName vs. RoutineName(). Differentiate between classes and objects The correspondence between class names and object names or between types and variables of those types can get tricky. Several standard options exist, as shown in the following examples: Option 1: Differentiating Types and Variables via Initial CapitalizationWidget widget; LongerWidget longerWidget; Option 2: Differentiating Types and Variables via All CapsWIDGET widget; LONGERWIDGET longerWidget Option 3: Differentiating Types and Variables via the "t_" Prefix for Typest_Widget Widget; t_LongerWidget LongerWidget; Option 4: Differentiating Types and Variables via the "a" Prefix for VariablesWidget aWidget; LongerWidget aLongerWidget; Option 5: Differentiating Types and Variables via Using More Specific Names for the VariablesWidget employeeWidget; LongerWidget fullEmployeeWidget; Each of these options has strengths and weaknesses. Option 1 is a common convention in case-sensitive languages including C++ and Java, but some programmers are uncomfortable differentiating names solely on the basis of capitalization. Indeed, creating names that differ only in the capitalization of the first letter in the name seems to provide too little "psychological distance" and too small a visual distinction between the two names. The Option 1 approach can't be applied consistently in mixed-language environments if any of the languages are case-insensitive. In Microsoft Visual Basic, for example, Dim widget as Widget will generate a syntax error because widget and Widget are treated as the same token. Option 2 creates a more obvious distinction between the type name and the variable name. For historical reasons, all caps are used to indicate constants in C++ and Java, however, and the approach is subject to the same problems in mixed-language environments that Option 1 is subject to. Option 3 works adequately in all languages, but some programmers dislike the idea of prefixes for aesthetic reasons. Option 4 is sometimes used as an alternative to Option 3, but it has the drawback of altering the name of every instance of a class instead of just the one class name. Option 5 requires more thought on a variable-by-variable basis. In most instances, being forced to think of a specific name for a variable results in more readable code. But sometimes a widget truly is just a generic widget, and in those instances you'll find yourself coming up with less-than-obvious names, like genericWidget, which are arguably less readable. In short, each of the available options involves tradeoffs. The code in this book uses Option 5 because it's the most understandable in situations in which the person reading the code isn't necessarily familiar with a less intuitive naming convention. Identify global variables One common programming problem is misuse of global variables. If you give all global variable names a g_ prefix, for example, a programmer seeing the variable g_RunningTotal will know it's a global variable and treat it as such. Identify member variables Identify a class's member data. Make it clear that the variable isn't a local variable and that it isn't a global variable either. For example, you can identify class member variables with an m_ prefix to indicate that it is member data. Identify type definitions Naming conventions for types serve two purposes: they explicitly identify a name as a type name, and they avoid naming clashes with variables. To meet those considerations, a prefix or suffix is a good approach. In C++, the customary approach is to use all uppercase letters for a type name for example, COLOR and MENU. (This convention applies to typedefs and structs, not class names.) But this creates the possibility of confusion with named preprocessor constants. To avoid confusion, you can prefix the type names with t_, such as t_Color and t_Menu. Identify named constants Named constants need to be identified so that you can tell whether you're assigning a variable a value from another variable (whose value might change) or from a named constant. In Visual Basic, you have the additional possibility that the value might be from a function. Visual Basic doesn't require function names to use parentheses, whereas in C++ even a function with no parameters uses parentheses. One approach to naming constants is to use a prefix like c_ for constant names. That would give you names like c_RecsMax or c_LinesPerPageMax. In C++ and Java, the convention is to use all uppercase letters, possibly with underscores to separate words, RECSMAX or RECS_ MAX and LINESPERPAGEMAX or LINES_PER_PAGE_ MAX. Identify elements of enumerated types Elements of enumerated types need to be identified for the same reasons that named constants do to make it easy to tell that the name is for an enumerated type as opposed to a variable, named constant, or function. The standard approach applies: you can use all caps or an e_ or E_ prefix for the name of the type itself and use a prefix based on the specific type like Color_ or Planet_ for the members of the type. Identify input-only parameters in languages that don't enforce them Sometimes input parameters are accidentally modified. In languages such as C++ and Visual Basic, you must indicate explicitly whether you want a value that's been modified to be returned to the calling routine. This is indicated with the *, &, and const qualifiers in C++ or ByRef and ByVal in Visual Basic. In other languages, if you modify an input variable, it is returned whether you like it or not. This is especially true when passing objects. In Java, for example, all objects are passed "by value," so when you pass an object to a routine, the contents of the object can be changed within the called routine (Arnold, Gosling, Holmes 2000). Cross-Reference Augmenting a language with a naming convention to make up for limitations in the language itself is an example of programming into a language instead of just programming in it. For more details on programming into a language, see Section 34.4, "Program into Your Language, Not in It." In those languages, if you establish a naming convention in which input-only parameters are given a const prefix (or final, nonmodifiable, or something comparable), you'll know that an error has occurred when you see anything with a const prefix on the left side of an equal sign. If you see constMax.SetNewMax( … ), you'll know it's a goof because the const prefix indicates that the variable isn't supposed to be modified. Format names to enhance readability Two common techniques for increasing readability are using capitalization and spacing characters to separate words. For example, GYMNASTICSPOINTTOTAL is less readable than gymnasticsPointTotal or gymnastics_point_total. C++, Java, Visual Basic, and other languages allow for mixed uppercase and lowercase characters. C++, Java, Visual Basic, and other languages also allow the use of the underscore (_) separator. Try not to mix these techniques; that makes code hard to read. If you make an honest attempt to use any of these readability techniques consistently, however, it will improve your code. People have managed to have zealous, blistering debates over fine points such as whether the first character in a name should be capitalized (TotalPoints vs. totalPoints), but as long as you and your team are consistent, it won't make much difference. This book uses initial lowercase because of the strength of the Java practice and to facilitate similarity in style across several languages. Guidelines for Language-Specific ConventionsFollow the naming conventions of the language you're using. You can find books for most languages that describe style guidelines. Guidelines for C, C++, Java, and Visual Basic are provided in the following sections. C ConventionsFurther Reading The classic book on C programming style is C Programming Guidelines (Plum 1984). Several naming conventions apply specifically to the C programming language:
These are the conventions for generic, UNIX-style and Linux-style C programming, but C conventions are different in different environments. In Microsoft Windows, C programmers tend to use a form of the Hungarian naming convention and mixed uppercase and lowercase letters for variable names. On the Macintosh, C programmers tend to use mixed-case names for routines because the Macintosh toolbox and operating-system routines were originally designed for a Pascal interface. C++ ConventionsFurther Reading For more on C++ programming style, see The Elements of C++ Style (Misfeldt, Bumgardner, and Gray 2004). Here are the conventions that have grown up around C++ programming:
As with C programming, this convention is far from standard and different environments have standardized on different convention details. Java ConventionsFurther Reading For more on Java programming style, see The Elements of Java Style, 2d ed. (Vermeulen et al. 2000). In contrast with C and C++, Java style conventions have been well established since the language's beginning:
Visual Basic ConventionsVisual Basic has not really established firm conventions. The next section recommends a convention for Visual Basic. Mixed-Language Programming ConsiderationsWhen programming in a mixed-language environment, the naming conventions (as well as formatting conventions, documentation conventions, and other conventions) can be optimized for overall consistency and readability even if that means going against convention for one of the languages that's part of the mix. In this book, for example, variable names all begin with lowercase, which is consistent with conventional Java programming practice and some but not all C++ conventions. This book formats all routine names with an initial capital letter, which follows the C++ convention. The Java convention would be to begin method names with lower-case, but this book uses routine names that begin in uppercase across all languages for the sake of overall readability. Sample Naming ConventionsThe standard conventions above tend to ignore several important aspects of naming that were discussed over the past few pages including variable scoping (private, class, or global), differentiating between class, object, routine, and variable names, and other issues. The naming-convention guidelines can look complicated when they're strung across several pages. They don't need to be terribly complex, however, and you can adapt them to your needs. Variable names include three kinds of information:
Tables 11-3, 11-4, and 11-5 provide naming conventions for C, C++, Java, and Visual Basic that have been adapted from the guidelines presented earlier. These specific conventions aren't necessarily recommended, but they give you an idea of what an informal naming convention includes.
Because Visual Basic is not case-sensitive, special rules apply for differentiating between type names and variable names. Take a look at Table 11-5. |
| < Free Open Study > |
EAN: 2147483647
Pages: 334