Naming things

How to call bits of code, apps, and such Edit

Table of Contents

  1. Why we need guidelines
    1. Avoid lingo and acronyms
    2. Use transparent names
    3. Consistent app/repo naming

Why we need guidelines

Engineering wisdom often says that code gets read an order of magnitude more often it gets written.

Understanding what’s written is paramount to building features, or, more critically, addressing issues — you wouldn’t want to have to dig into documentation, or hunt for the appropriate person, when you’re having to diagnose an incident occuring in production.

Avoid lingo and acronyms

Lingo and acronyms make onboarding engineers much harder. Even after onboarding, they’re a source of pain as different teams can build up lingo that reflects their particular concerns.

Recommendation: favour explicit terms over lingo, and expand acronyms.

In non-code contexts (wiki pages, emails), it’s fine to use abbreviations as long as the first use in the document is expanded.

Use transparent names

Fancy names are a staple in software engineering. Who doesn’t like a cool name or a backronym!

They’re also often hard to interpret if you’re not already aware of what they stand for

Even more importantly, using a “fancy name” when naming classes, apps, or repositories can be a smell that the purpose or scope is ill-defined.

Recommendation: give names that reflect the domain and usage:

Consistent app/repo naming

We want it to be easy to locate the codebase for a given app, especially when hunting down issues.

Fortunately we honour 12-factor, which means each app is backed by exactly one repo.

Recommendation: App names should be exactly roo-{repo}-{env}, with the roo- prefix optional if unambigous.

Examples: restaurant-portal-staging, roo-it-production (with the caveat that DNS places a 32-character limit on domain name parts).