12.3  External identifiers

“Short words are best and the old words when short are best of all.”

                                                —Winston Churchill

When defining exported symbols, clarity trumps brevity: The client programmer can always define abbreviations as desired.

• Construct exported identifiers from complete words separated by underbars. Do not use word fragments; do not drop vowels; do not run words together. Use acronyms only when universal, such as ASCII.
• A verb followed by a noun makes a good function name.
• An adjective followed by a noun makes a good type or constant name.
• Eschew obfustication. Prefer short, plain words whenever practical. Do not utilize utilize; use use.

Be specific — call a rock a “rock”, not a “thing”. Do not be coy; do not keep secrets from the reader. Programs are not murder mystery novels.

When you pick an external identifier, your target audience should be someone who has never heard of your package, someone who is diving into an unfamiliar ten-million-line program with thirty minutes to fix an obscure bug before people start dying. This person does have time to puzzle out cryptic identifiers; they need to be blindingly obvious.

Save a life: Make your external identifiers exactly as long as they need to be, neither more nor less. Sweat blood to make them clear.