There is an expression that states: “There are only two hard things in programming – cache invalidation and naming things”. More often than not, so little effort goes into naming things. We’re usually eager to start working on the “important” stuff as soon as possible so in a matter of seconds we make up a name that is going to be the first and most important point of contact for anyone looking into that particular part of the implementation. The name of a variable, function, class or any type should roughly tell you what it does, how it’s used and why it exists. That is why much more thought and effort should go into naming things.
Using nouns, verbs and prefixes
When naming a type, like a class or a struct, it is a good practice to use nouns and never verbs, e.g. Artist, Track, Album, User etc. Methods perform some kind of work so they should contain a verb, e.g. saveTrack, deleteUser. For values, you should prefix getters and setters with get/is/set. It is important to ensure that names describe the implementation. When someone looks into the code behind a certain name, it is important that they find exactly what they expected. That is why it’s fine to make names longer, in order to better describe the implementation. You should always keep in mind that you’re writing this code for someone else. You want them to know what is implemented just by reading the function name.
When naming similar types it is very important to keep the names sorted together alphabetically by a common prefix. Usually the name of the class consists of what is common to other classes, followed by what is specific about particular implementation. For example, when multiple classes are used to develop a feature, the name of a specific class consists of feature name followed by the description of that particular class:
Don’t forget the constants
For constants, it is a good practice to always use names that you can look up. The names for constants also give a description of what they are used for. Most developers use constants for “global” data elements only, i.e. data elements that are used all over the app. The problem is when the scope is constrained to a class or even a method. I often run into code that just uses a number instead of a named numeric constant, and it is a problem because you don’t know why that particular number is used there. Only after looking at the context you might be able to figure out what that number is used for. Sometimes there is a comment about that number, but it’s much better to have code that comments itself. If a constant is named e.g. MIN_CELL_PADDING or MAX_ITEMS_TO_DISPLAY, it would be clear what the purpose of that constant is, and there would be no need for a comment.
Adding comments to a part of implementation, or variable and function names can usually be considered as a code smell. If you need a comment for a name or some part of the implementation, you should probably consider to refactor it.
There are similar types of names that are equally appropriate for some implementation. For example, let’s say you have a class that manages data about the users of your application. It performs some network requests and transforms response data into model entities that are used by a number of other classes in the project. An appropriate name for that class would be UsersDataController, but it would be fine to use UsersDataManager or UsersDataService. So whether it’s Controller, Manager, Service or similar is less important, what’s really important is that these names are used consistently by all members of the development team. It would be a bad practice to mix those and end up with UsersDataManager, TracksDataService and AlbumsDataController in the same codebase.
If you liked this blog post I’d appreciate if you followed me on Twitter