Describing code? Avoid these words.

When we describe code, we tend to use confusing words. Re-think your language with this simple guide.

These quick tips apply to README files, code comments, API documentation, reports, research papers, websites, elevator pitches and water-cooler conversations.

“Automatically” means “without human control.” Who is responsible for what the code does, then? Clarify and nix “automatic.” Instead of “the program places an order automatically,” say: “this function places an order via the FooBar API.”

“Manually” means “using hands.” Whose hands? Clarify and nix “manually.” Instead of a code comment like, “this will require manually sorting the list,” say: “the end user may sort the list” or “the front-end JavaScript can sort the list” or “the programmer can sort the list” or “this function sorts the list” — or whatever else you meant.

“Magically” and “magic” and — gasp — “automagically” mean “using supernatural forces.” Don’t use this word unless your code literally uses supernatural forces … in which case you’ll need lots more documentation.

“Fast” and “Slow” seem to mean “fast enough” and “too slow” — but they don’t. Use language that helps readers make decisions. Instead of “this function is fast,” specify: “this function is O(n) with respect to input bytes” or “this function handles 200,000 orders per second on an i5–6600K with 8GB RAM” or “this function indexes documents four times faster than Lucene 6.5 on similar hardware.” Describe how you calculated these results. If you have no proof, don’t mention speed at all.

“Hard” and “Easy” seem to mean “too hard” and “easy enough” — but they don’t. Use language that helps readers make decisions. Instead of “this interface is easy to use,” specify: “this interface has three input fields, and it reports user errors client-side using JavaScript.”

“API” means “application programming interface.” We know you’re Programming; now specify the Application (usually a brand name) and the Interface (something like HTTP, REST, SOAP or Java RMI). So instead of “API,” write “the Twitter REST API”. “The Twitter REST API” is clear, and it’s perfectly okay to write “the Twitter REST API” 200 times in the Twitter REST API’s documentation and comments. Let it never be said that you wrote “API” on its own and one reader somewhere didn’t realize you meant “the Twitter REST API.”

Long, rare words may prove you’re educated, but they confuse readers. The code is confusing already — that’s why you’re talking about it, right? Use short, common words. Also, avoid run-on sentences: prefer periods to commas.

Design-pattern names are great — when your readers are familiar with them. Many coders don’t know what a design pattern is. Instead of “this is a facade,” write: “this wraps the Foo and Bar packages using the facade pattern.” Specify which piece of the design pattern you mean: if you’re writing about the bridge pattern, is this class the abstraction or the implementor? Be extra-clear if the pattern isn’t a Gang of Four pattern. If your code’s design or terminology isn’t exactly like Wikipedia’s illustrations, explain why.

For bonus points, read your documentation out loud before publishing it. If your sentence sounds confusing, rework it. If your documentation makes your code sound confusing, make your code do something simpler.

Great conversations lead to great code. Write and speak clearly to make something special.