Embarcadero CodeRage 2019 is Here !

Embarcadero’s annual on line series of webinars is back again !

This time they’ve changed the format to make it a large number of smaller videos, allowing you to dip in and out much more easily.

There is an overall theme for each week.

 For more about CodeRage 2019 (including the list of each of the active weeks and how to register) go to Jim’s CodeRage2019 Blog

 

Naming arguments and variables: Index and Number

It’s very common to have integers that are used to count objects. It’s also very common to have integers that are offsets into arrays (or similar structures).

Humans tend to count from 1 to n. In almost all cases when software uses offsets it makes sense to design the offset to run from 0 to n-1. Sometimes it is obvious which applies to a variable or function parameter. Sometimes this starts off being obvious but with the passage of time and the increase in the code complexity it becomes less obvious (even to the original code author). I know because I’ve been there.

There are also cases where it may not be so obvious from the start. Suppose you have a function which is passed the user response to the question “which one in this list of items do you want?”. Does the function return “1” if the user want’s the first one in the list or does it return zero?

I strongly encourage the use of the words “Index” in variable names which are expecting 0 to n-1 values and “Number” in variable names which are expecting 1 to n variables.

Thus you might declare the above function as

int GetUserSelectedNumber(void);

if the function returns 1 if the user selects the first item, or

int GetUserSelectedIndex(void);

if the function returns 0 if the user selects the first item.

Similarly if you have three things to control stored in an array, you might write:

const int NumberOfWidgets = 3;
TWidget Widgets[NumberOfWidgets];

and you could have a function somewhere that is declared as

void DoSomethingWithWidget(int WidgetIndex);

This is then immediately clear to everyone that the integer passed must run from 0 to n-1 (ie 0 to 3).

It’s a simple naming convention but it can save you hours when supporting your older (ongoing) code..