/
2. Names

2. Names

Jan 22, 2013

 

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()

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

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

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

For Portability

  •  

    • For a null pointer, use "NULL".

2.7.2 Reference Variables

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.