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 oversimplifed

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.

Page 36 3.3

1.5 KiB Raw Blame History