Use Domain Terminology
| » | class Person { |
| » | String lastName; |
| » | String role; |
| » | int travels; |
| » | LocalDate employedSince; |
| | |
| » | String serializeAsLine() { |
| | return String.join(",", |
| | Arrays.asList(lastName, |
| | role, |
| | String.valueOf(travels), |
| | String.valueOf(employedSince)) |
| | ); |
| | } |
| | } |
The code you work on usually belongs to a specific domain, and a domain has its own vocabulary. Think of sports; different sports have their own domain-specific names for hurling, throwing, kicking, bending, or dunking a different kind of ball. The more you insert the terms of your program’s domain into your code, the better.
In the code above, you see a class for representing a person with a last name, a role, the number of travels, and the date of employment. The class is quite generic, and you can probably find something similar in most systems that store employee data. You might still wonder why the code uses exactly these attributes. Why does it only consider the last name and not also the first name? And why does it track the number of travels?
The name of the method, serializeAsLine(), is quite generic, too. From that name, we only know that this person’s fields are serialized to a string without line breaks. But we don’t know if there’s something specific about the format.
Take a look at how domain-specific naming improves the readability of the code:
| » | class Astronaut { |
| » | String tagName; |
| » | String rank; |
| » | int missions; |
| » | LocalDate activeDutySince; |
| | |
| » | String toCSV() { |
| | return String.join(",", |
| | Arrays.asList(tagName, |
| | rank, |
| | String.valueOf(missions), |
| | String.valueOf(activeDutySince)) |
| | ); |
| | } |
| | } |
In this book, we put the code examples in a domain inspired by a Mars mission, and we fit all the names into this particular domain. This automatically makes the code much clearer.
When it’s put into context, the meaning of the different attributes is much easier to understand. First of all, we want to store data about an Astronaut and not just a Person, and that should be obvious from the class name. Of course, an astronaut is also a person in real life, but we’re only interested in astronaut-related aspects. In this setting, the lastname is meant to be the writing on the tag an astronaut is wearing, the role actually refers to the rank she’s in, and now travels is also much clearer since it’s supposed to refer to the number of missions in space. In the same fashion, employedSince actually refers to the activeDutySince.
But the Mars mission isn’t the only domain in the class. Code deals with technical concepts, which means that you’re always implicitly in a technical domain with its own terminology. Because of this, we renamed the method serializeAsLine() as toCSV(). After all, the resulting format of the serialized representation of an astronaut is a line of comma-separated values. This makes the meaning of the method more obvious to most programmers, simply because the term CSV is very common in the programming domain, as we’ve seen in Avoid Abbreviations.
To sum up: You should align names in your code to the domain it belongs to as far as possible and avoid generic names.