Write Your Code Like Prose

Use nouns for things and true functions. Use verbs for procedures (actions with side effects). Use adverbs for functions that slightly tweaks how another verb works. Use adjectives to indicate decorators. If your language lacks support for KeywordParameterPassing, then use a gap character to indicate a place for a parameter. Just as printf() takes %this and %that to indicate places to fill in with data, so too can you write meaningful function/procedure names:

  List *take_itemsFrom_ (int, List *);
  void  moveWindow_to_  (Window *, Point);
  void  withOpenFile_do_(char *, void(*)(FILE *));

In some cases, it's possible to get by with a noun phrase for a procedure with side-effects. In this case, you're treating the procedure definition almost like a declaration.

  void lineItem(void) {
    quantity(); skuNumber(); description(); unitPrice(); totalPrice();
  }

This is common in ForthLanguage, but in CeeLanguage, it's pretty awkward. Use your best judgement.

The point: write your program so as to be a truely executable description of what it does, or something as close to it as possible. If your language lacks a specific control flow operator to do this (e.g., in C, there is no equivalent to "for each"), then make one using function pointers (e.g., forEverythingIn_do_(List *, void(*)(Node *)), or more traditionally, map_ontoList_(void (*)(Node *), List *) ). Unless performance is paramount, it'll always be "fast enough." It also forces you to refactor your code into smaller pieces, which are easier to maintain and, yes, to even read.

This is the one of the kingpins of XP. It's the core of Smalltalk's coding style. And it's just plain common sense. Which is precisely why it's not so common. This is disturbing.

Arithmetic notation used in programs is good if your intended audience is going to have a math degree. Most of us don't. When we code, whether it is in a FunctionalLanguage or ImperativeLanguage, we tend to think in terms of, "This has to happen, and this has to happen, and then this has to happen." Write your code as such.

TellDontAsk is a critical requirement in making easy to read code. It applies just as much to procedural code as it does to OO and functional code.


I HaveThisPattern - I have started to write my boolean-value-accessor methods with names like deviceIsPoweredOn() and objectIsPrepared() just so my logic reads like English - if(objectIsPrepared()) processObject() --PeteHardie

Yeah -- me, too. However, I tend to make the lookup verbs a little more logic friendly, so it becomes IsDevicePowered?() and IsObjectPrepared?(), where obviously the answer is either yes or no, true or false. The use of "Is" or "Get" or "Set" as the first word in the name of the method immediately tells me what the purpose of the operation is, rather than have to read the whole CamelCaseWord and dig out the intent. For me, it's ask before telling. Six of one, half dozen of the other. YMMV. Void Where Prohibited By Law. -- MartySchrader


EditText of this page (last edited May 5, 2010) or FindPage with title or text search