2. Names

Owned by Deepa Chavali
Last updated: Jan 22, 2013Version comment
5 min read

 

2. Names

In General, choose names that are meaningful and readable. All names should be in English. If the name is appropriate everything fits together naturally, relationships are clear, meaning is derivable, and reasoning from common human expectations works as expected.

  • When confronted with a situation where you could use an all upper case abbreviation, you can do so; or instead, you can use an initial upper case letter followed by all lowercase letters.

class FOVPanel

class UtcDate

openDVDPlayer();

exportHtmlSource();

InertialReferenceUnit theIRU;

FineSunSensor         theFss;

  • Avoid use of underscores.
2.1 Class Names
  • Capitalize the first letter of each word. 
  • A GUI component class name should be suffixed by the parent component name.

class MainFrame : public Frame class DisplayPanel : public Panel

  • Exception classes should be suffixed with Exception. 

InvalidEulerSequenceException

2.2 Class Library Names
  • Prevent class name clashes by using namespaces.
  • When few components of a namespace are used in a file, the code should avoid using 'using' clauses and should use the scope operator '::' instead; however, when there are many uses of namespace components, it is preferable to use a 'using' clause to avoid clutter in the code.
2.3 Class Instance Names
  • For instances of classes, follow conventions for variables
2.4 Method / Function Names
  • Every method and function performs an action, so the name should make clear what it does. Names should be verbs and written in mixed case starting with upper case.

OutputCalibrationData()

Normalize()

  • Prefixes are recommended:
    • Is/Has/Can -to ask a question about something and return bool type
    • Set/Get -to set/get a value
    • Initialize -to initialize an object
    • Compute - to compute something, or
    • Calculate - to calculate something
  • The name of the class should not be duplicated in a method name.

Vector Normalize()// NOT: Vector NormalizeVector()

  • When coding from the formal specification, match names with the spec but use no underscores.
2.5 Method / Function Argument Names
  • Use the same guideline as for variables. 
  • When passing a class, an argument can have the same name as its type. This is not required, however, and in some cases may even be cumbersome. In that case, the name should be succinct.

void SetForceModel(ForceModel *forceModel)

void SetForceModel(ForceModel *fm)

  • When coding from a formal specification, match argument names with the spec if possible, but use no underscores.
2.6 Namespace Names
  • Use the same guideline as for class names. It is suggested to use the project name as a prefix for the namespace name, to avoid name clashes.

namespace GmatTimeUtil 

2.7 Variables
  • Variables should begin with a lowercase letter, with the first letter of each word (after the first) in the name capitalized.

double flatteningCoefficient; MaVector3 initialPosition;

  • Add a comment to a variable declaration if the meaning is not clear from the variable name. 
  • Internal variables should be declared at the level at which they are needed. For example, if a variable is used throughout the procedure, it should be declared at the top of the procedure. If a variable is used only in a computational block, for example, it may be declared at the top of that block. 
  • Internal variable declarations should be commented well, if their meaning is not clear from the variable names (particularly useful is a comment about units; units may be included in the variable name as well, e.g. initialPositionInKm) 
  • The declaration of indices may be inside a for loop or above it. (If that variable is needed after the execution of the loop, it will need to be declared above, not inside, it.)

for (Integer I = 0, bool done = False; i < MAX_SIZE && ! done; i++)

{

...

}
Or
Integer i; // loop counter bool done; // have we found the matching item? for (i = 0; i < MAX_SIZE && ! done; i++)

{

...

}

  • It is preferable to use the project-defined types instead of the built-in types for the loop indices (e.g. use Integer instead of int).
2.7.1 Pointer Variables
    • Place the '*' with the variable name rather than with the type:

MAB::String *name = new MAB::String;

MAB::String *name1, address; // note, only name1 is a pointer

    • Take care using pointer conversions, particularly conversion from a base type to a derived type

For Portability

    • For a null pointer, use "NULL".
2.7.2 Reference Variables
    • Put the '&' with the variable name rather than with the type.

MaString(const MaString &maString, unsigned int bufferLength = 0) Quaternion Rate(const Vector3 &w) const;

    • For class overloaded operators and methods returning a reference, put the '&' with the type.

const MaString& operator= (const GSSString &gssString); const MaString& operator= (const char *string); const MaSString& operator= (char ch); char& operator[](unsigned int index); const MaVector3& Normalize();

2.7.3 Global Variables
    • Use of global variables should be avoided. Instead, use namespaces.
2.8 Type Names
  • Type names should have the first letter of each word capitalized.

typedef unsigned int SystemType typedef double RealType typedef ArrayTemplate<RealType> RealArrayType; typedef TableTemplate<RealType> RealTableType;

2.9 Enum Type Names and Enum Names
  • Enum types should follow Class Name policy. 
  • Enumeration constants should be declared using all caps and underscores between words.

enum DayName {SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY}; enum Color {RED = 3; BLUE, DARK_BLUE, GREEN, DARK_GREEN, YELLOW = 7};

  • Enumeration constants can be prefixed by a type name.

enum Color {COLOR_RED, COLOR_GREEN, COLOR_BLUE}; 

2.10 Constants / #define
  • Constants should be declared using all CAPS and underscores between words.

const int MINIMUM_NUMBER_OF_BYTES = 4;

  • The use of #define statements should be avoided. const variables or enumeration types should be used instead of constant macros. (An exception is when conditional debug is included - #define statements may be used then).

use
const unsigned int MAX_NUMBER_OF_FILES = 4;
instead of
#define MAX_NUMBER_OF_FILES 4

2.11 Structure Names
  • For structure names, follow conventions for class names with the word "Type" when appropriate.

struct TimeType { IntType year; IntType month; IntType day; IntType hour; IntType minute; RealType second; };

  • Use of classes is preferred to structs. However, if all data is public, a struct may be used. 
  • The developer may use structs to encapsulate global data (including exceptions).

struct AttitudeTypes { static const RealType TEST_ACCURACY; // value is 1.19209290E-07F };

2.12 C Function Names
  • For C functions use C style function names of all lower case letters with '_' as word delimiter.

get_best_fit_model() load_best_estimate_model()

  • There should be very few C functions used in a C++ program. They should just be used to interface between C++ and C code.
2.13 C++ File Names
  • All C++ header files should have the suffix of .hpp 
  • Header files which contain code that is accepted by both C and C++ compilers should have the file name extension ".h". 
  • C++ source files should have the suffix .cpp 
  • File names should match, as much as possible, the name of the class declared or defined within it, and should have the .hpp or .cpp suffix, as appropriate.

If class name is AnalyticalModel, the file names should be:
AnalyticalModel.hpp AnalyticalModel.cpp

2.14Generated Code File Names
  • Don't change the naming convention for files generated by other programs (e.g. wxWidgets).