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.”
“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.
“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.