Via Hacker News, my one social-media vice, I get exposed to a lot of technical blog posts, websites advertising software, and general Silicon Valley-speak. Like most people who read plenty, or write themselves, I have ended up with Certain Opinions on the right and wrong way to do these things, and must confine my pedantry to a safe little habitat so that it can’t loose itself upon an unsuspecting party.
Hence, the Style Guide.
I don’t expect this to be useful to you. But I can’t physically stop you from reading it. Perhaps someone will feed it to an LLM in order to sound more like me.
A runtime is the system which supports a program during run time, the period of execution (as opposed to compile time). As adjectives those phases are run-time and compile-time.
Garbage collection commonly refers to the tracing kind, as opposed to things like reference counting or borrow checking, but nit-pickers will complain that RC is a kind of GC. You are better off talking about systems for memory management and clarifying whether they use tracing, counts, static analysis or whatever.
Type may be the most overloaded word in computing. As academic jargon, it means a compile-time description of a given variable’s possible values. But the word is used even in languages with no such concept, such as for run-time reflection on objects, or when defining data structures and schemas, not to mention the normal meaning (as variety or category). This all leads to confusing recursion: there are many types of types. Kind has also been appropriated by theorists to refer to meta-types, but that word’s normal use is less likely to mislead. Types are unavoidable, but specify.
Semantics is similarly overloaded, and worse lacks familiar usage outside of programming. Prefer meaning or behaviour unless you know what you’re doing.
An API describes the methods used to interact with a software library or web service. The term is so familiar to programmers that it’s rarely expanded to the unhelpful application programming interface. Avoid the orphaned initialism and stick to plain interface or web service, with appropriate context.
An issue is a topic for discussion, and in software specifically, often a numbered ticket tracking a given bug report or feature request. But the map is not the territory: you may debate or close an issue, but you find and fix a problem.
Ergonomic is not an ergonomic word, any more than heterological is. Save it for the ugly office chairs and try practical, intuitive, simple etc instead.
Similarly powerful is no longer powerful, thanks to overuse by JavaScript wrapper libraries and whatnot. Capable is a less overblown synonym, but better still, figure out what you mean.
Performant stinks. High-performance is more standard, but efficient is usually a better synonym, or commit to fast. Most performant is fastest!
Same goes for utilise. If you are not a chatbot or PR firm, you have no reason to utilise this word (or worse to leverage it) if you could use another.
Effectively is common but formally means with effect, rather than in effect. It’s probably too late to argue this point effectively. But I try to be precise about it myself.
Some clichés to avoid:
- at the core
- under the hood
- down to the metal
- low-hanging fruit
- dogfooding
- craft (as in make or write)
- sunset as a verb
- blazing fast
- battle-tested
- industrial strength
- production ready, in production etc
- end result / net result (results always come at the end!)
No doubt more to come as I encounter more bothersome blog posts.