Introduction

It is easy to write software that works satisfactory. But it is very hard to write reliable, understandable and maintainable code. One important aspect is using good variable and function names. Variable names must be:

  • Understandable
  • Descriptive
  • Pronounceable
  • Need no comment

I have created a list of examples that will help you to quickly find variable names.

Recommendations

Self documenting code

General spoken, when comments are necessary, the code is not written well. Don't use comments at each line of code; the code should be self documenting. But of course comments are needed for the big picture.

Here is a c++ codefragment where I applied the technique of self documenting code:

int CurveTracer::trace(bool printCurve, int _averaging, int stepTime_ms)
{ const int mVstep=5;
averaging = _averaging;
int Wire_mOhm = 2;
int mV=0, mA=0, mW=0, mWpeak=0, mVnext=0;
if(printCurve) Serial << F("\n\nmV mA mW ");

for(int i=0; i<=1023; i++) 
{ measure(i, stepTime_ms, mV, mA);    
correctForWire(Wire_mOhm, mV, mA);
if(i==0) 
{ mAoffsetError = mA; // I should be 0 at start but isn't
mVstart = mV;
mVnext = mV;
}    
repairOffsetError(mV, mA);
calcPower(mV, mA, mW, mWpeak);

if(mV <= mVnext) // measurement direction 80 75 70mV
{ if(printCurve) dataOut(mV, mA, mW); 
//testOut(i, mVnext); // only for test     
mVnext = mV - mVstep;
}
}
Serial << F("\nmWpeak: ") << mWpeak;
delay(1000); // pause time to read from screen
return mWpeak;
}

Common naming rules

  • Classes begins with uppercase.
  • Variables, objects, member functions etc. begins with lowercase.
  • For containers use plurality 's' notation (personIDs), for the container items use singular notation (personID).
  • Don’t use the Hungarian notation anymore, where the name indicates its type (iNumLines).

Examples of good and wrong variable names

  • generateTimestamp() instead of genymdhms (generation date, year, month day, hour, minute and second).
  • checkForErrors() instead of errorCheck().
  • dumpDataToFile() instead of dataFile().

Avoid different variable names for the same thing

  • fetch, retrieve, get
  • controller, manager

Avoid meaningless variable names

  • data, info, class, object, string

Variable names abbreviations

msg message
dlg dialog
cfg configuration
err error
val value
fmt format
cnt count
tmp temp
str string
parm parameters
arg argument
ini initialization
cmd command

Variable names examples

One letter variable names

  • indices: i, j, k (k varies fastest)
  • coordinates: x, y, z
  • pointers: p, q, r
  • time: t
  • starting time: t0

Popular variable names

  • result (returnValue)
  • max, min
  • index
  • next
  • digit
  • n_Lines
  • numLines
  • errorCount
  • cnt (the current count of a running count variable)
  • key (container lookup key)
  • get, set
  • tmp_float (temporary values)
  • failure, success (enummeration values)
  • arg (function argumement)
  • item (containers items)

Variable names examples

  • personID
  • testResult
  • fullName
  • retryMax
  • retryCnt
  • arraySize
  • limit
  • numberOfBooks
  • currentName
  • fromValue
  • toValue
  • colorCollection
  • elapsedTimeInDays
  • daysSinceCreation
  • daysSinceModification
  • fileAgeInDays
  • timeToOpenDoor
  • daysDateRange
  • flightNumber
  • carColor
  • fileOpenItem (menu items)

Boolean variable names examples

  • isEmpty()
  • isEnabled()
  • shouldAlarm
  • started
  • canUndo
  • showGrid

Function names examples

  • person.name()
  • person.changeNameTo("mike")
  • sumOf()
  • countUpTo()
  • setupTest()
  • adjustFrame()
  • fileOpenAction() (menu actions)

Constant names examples

  • maxDaysPerMonth
  • distanceToTarget_centimeters
  • MAX_INPUT
  • NUM_DATA_POINTS
  • NUMBER_OF_CONSUMERS
  • MAX_BUF_LENGTH

File names examples

  • Boxes: BFormatGridBox.cpp
  • Forms: FMainForm.cpp

 

 

Do you have any comments? Please let me know.
Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.