picture home | pixelblog | qt_tools

David Van Brink // Fri 2007.10.26 18:50

Basics: Write Short

Code comments and email subject lines should be as short as possible, and no shorter. They don’t have to be full-featured English.

Basics: Write Short

In writing, brevity is a virtue. Samuel Clemens, responding to one particular excess, wrote: “Substitute ‘damn’ every time you’re inclined to write ‘very’; your editor will delete it and the writing will be just as it should be.” There appears to be a misperception that great meaning requires lengthy prose; but to misuse Yoda’s words: “Size matters not.”

The title of this post was “How to write short”, then “Please write short”, and, finally, “Write Short”. Brevity is of especial importance in code. Other contexts of critical brevity include:

  • code comments
  • email and bug-report subject lines
  • blog posts

Code: Get Rid of Of, and And, and To, Too

(I’ve noted some of the patterns, but I suspect my nomenclature is flawed. Improvements welcome.)

nameOfPort should be portName (noun aspect pattern)

getNumberOfFish() should be getFishCount() (verb aspect noun pattern)

saveIfNecessary() can be maybeSave() (adv verb pattern, & your reader can trust you)

addFishToPond() should be addPondFish() (verb dest source pattern)

And my favorite: the_address_line_to_the_uart1 should be uart1_address (noun aspect pattern)

Code Comments: What, Not How

There’s plenty of available wisdom on comments; a veritable commentary of commentaries on the subject, even. I’ll offer just one example of comment shortness.

// set n to the number of fish

should be

// n is the fish count

How it happens is the code; what has happened may be worth a comment.

Email & Bug Report Subject Lines: Frontloaded Please

The important thing to remember is that email and bug report lists often appear in tabular form, with the Subject column truncated. Keep it short, and lead with the most important words.

Help!!! I opened the document and then selected the first block and it froze!

Should be…

Freeze after Open & Select-Block

And that’s enough of that. On to our last area of brevity…

Blog Posts…

Guilty, but I’ll try harder. Bye now.


(c) 2003-2011 omino.com / contact poly@omino.com