Skip to content

Naming

In every software system we build, and every API we design or use - there are names that will live far longer than we ever intend them to. It is important to choose great names.

Why do names matter?

When designing and building an API, the names we use will be seen by & interacted with all users of the API.

What makes a name "good"?

Expressive

It is critical that a name clearly convey the thing is it naming.

  • e.g. The term topic is used in both messaging and machine learning.
  • If your project includes both using the name topic will be confusing.
  • A more expressive name is required:
    • topic_model
    • topic_message

Simple

  • While an expressive name is important, it can also become burdensome if the name is excessively long without adding additional clarity.
  • Names should be expressive but only to the extent that each additional part of a name adds value to justify its presence.
  • On the other hand, names shouldn't be oversimplified
Name Note
UserSpecifiedPreferences Expressive, but not simple enough
UserPreferences Both simple & expressive
Preferences Too simple

Predictable

  • In general, we should use the same name to represent the same thing, and different names to represent different things.
  • The basic goal is to allow users of an API to learn one name and continue building on that knowledge to be able to predict what future names would look like.

Language, Grammar & Syntax

Language being inherently flexible and ambiguous can be a good thing and a bad thing.

  • On the one hand, ambiguity allows us to name things to be general enough to support future work.
    • Naming image_url rather than jpeg_url presents us from limiting ourselves to a single image format.
  • One the other hand, when there are multiple ways to express the same thing, we often tend to use them interchangeably, which ultimately makes our naming choices unpredictable.

Language

Use American English.

Grammar

Imperative Actions

REST standard verbs should use the imperative mood. They are all commands or orders.

  • isValid(): Should it return simple boolean field? Should it return a list of errors?
  • GetValidationErrors(): Clear that it will return list of errors, empty list if is valid.

Prepositions

  • If a Library API wants to list Book resources with the Author, it's tempting to name BooksWithAuthor.
  • This falls apart when we add in all our additional resources
  • We will end up with many function names to call.
  • The preposition with is indicative of a more fundamental problem.
  • Prepositions act like code smell, hinting at something not being quite right.

Pluralisation

  • Most often, we should use the singular.
  • However collection names might be pluralised.
    • Use American English to pluralise.

Context

  • When we use book in the library API, we are referring to the resource, however in a flight booking API - we are referring to an action.

This means we need to keep the context of our API in mind.

  • Context can impart additional value to a name that might otherwise lack a specific meaning.
  • It can also lead us astray when we use words with a specific meaning but don't make sense without the context.
    • record is very generic, until you consider the context of an audio recording API.

Data types and units

A name can become more clear when using a richer data type.

  • dimensions: String; - this is ambiguous
  • dimensions: Dimensions; (where Dimensions is an object)