Names (first in a series)

It's hard to over-emphasize the importance names bring to the maintainability of code. They're the first thing a maintainer sees, and they're often the last thing a novice code thinks about. Textbooks provide notoriously bad examples that students follow in the real code.

If you haven't already, spend some time at Roedy Green's How to write unmaintainable code. Note that the longest essay there is on naming.

Unfortunately, there is no formula for generating names, just some good heuristics, and some major "don't"'s, like names that are

• cryptic, e.g., bltx
  
  
• vague, e.g., data
  
  
• verbose, e.g., first-item-to-delete
  
  
• misleading, e.g., num for something that holds a
  list of numbers
  

Good names are:

• short
  
• plain English or conventional
  
• accurate
  

A function name should

• say what a function returns or does, e.g., get-test,
  never how it does it, e.g., search-recursively
• be either a verb-object, e.g., get-test, or
  qualified-verb, e.g., string-sort
• be semantic for application-specific functions, e.g.,
  remove-test-case
• be generic for general utilities,
  e.g., reverse-sequence

Much more to come on this topic.

Addendum: Just to reinforce the importance of naming, see
page 5 of Where the Wild Bugs Are.