Naming

The Practice of Programming

Naming

• Use capital letter for constant

#define ONE 1

• Include a brief comment with the declaration of each global
• Use descriptive names for global.

int npending = 0; // current length of input queue

• Use short names for locals. Compare

for (theElementIndex = 0; theElementIndex < numberOfElements; theElementIndex++)
  elementArray[theElementIndex] = theElementIndex;

to

for (int i =0; i < nelems; i++)
   elem[i] = i;

• Other naming conventions and local customs.
  • Use names that begin or end with p, such as nodep, for pointers;
  • Initial capital letters for globals;
  • All capitals for constants;
  • Use pch to mean a pointer to a character;
  • strTo and strFrom to mean strings that will be written to and read from;
  • It is a matter of taste as for the spelling of the names themselves: npending or or numPending or num_pending.
• Be consistent. Give related things related names that show their relationship and highlight their difference. For example

class UserQueue {
  int noOfItemsInQ, frontOfTheQueue, queueCapacity;
  public int noOfUsersInQueue() { ... }
}

can be better changed to

class UserQueue {
  int nitems, front, capacity;
  public int nusers() { ... }
}

• Use active name for functions. Functions names should be based on active verbs, perhaps followed by nouns:

now = date.getTime();
putchar('\n');

Functions that return a boolean value should be named so that the return value is unambiguous. Thus

if (checkoctal(c)) ...

does not indicate which value is true and which is false, while

if (isoctal(c)) ...

makes it clear that the function returns true if the argument is octal and false if not.

• Be accurate. A name not only labels, it conveys information to the reader. For example, the function name below is doing the opposite of what it has been implemented.

public boolean inTable(Object obj) {
  int j = this.getIndex(obj);
  return( j == nTable);
}

Expressions and Statements

• Indent to show structure
• Use the natural form for expressions.

if (!(block_id < actblks) || !(block_id >= unblocks)) ...

is not good compare with

if ((block_id > actblks) || (block_id < unblocks)) ...

• Parenthesize to resolve ambiguity.
• Break up complex expressions
• Be clear. For example ?: operator is fine for short expressions , as in

max = (a > b) ? a : b;
printf("The list has %d item%s\n", n , n==1 ? "" : "s");

but it is not general replacement for conditional statements.

• Be careful with side effects. For example, the '++' operator and I/O. For example, the following is wrong because all the arguments to scanf are evaluated before the routine is called.

scanf("%d %d", &yr, &profit[yr])

The fix is

scanf("%d", &yr);
scanf("%d", &profit[yr]);

Consistency and Idioms

• Use a consistent indentation and brace style.
• Use idioms for consistency.