Meaningful names

your_name_hereThere 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.

Similar types

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:

OnboardingWizardView
OnboardingWizardViewModel
OnboardingWizardDataSource
OnboardingWizardDetailsView
OnboardingWizardDetailsViewModel

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.

Comments

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.

Consistency

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

Related Post

Remember to share...Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInEmail this to someone

2 thoughts on “Meaningful names

  1. I think common prefixes for class/type names should be avoided.

    I’ll give a concrete example, from Python’s standard library. There’s a module called lzma, which contains (among other things) three classes – LZMAFile, LZMACompressor, and LZMADecompressor, exactly as you suggest.

    The problem, though, is that prefixing each name with LZMA does nothing to help understanding. The classes are already grouped together under the lzma module, so prefixing all their names with LZMA just duplicates that information – their fully qualified names would be lzma.LZMAFile (and so on). Dropping the LZMA prefix, turning them into lzma.File (and so on) doesn’t remove any information or hinder understanding, but it would eliminate some noise in the code.

    If you’re using a language that doesn’t have a real module system – for example, C just dumps everything into the global namespace – then prefixing functions or types like that makes sense. But, otherwise? Don’t bother. The module or submodule itself acts as a prefix.

    1. Hi Kevin, this is not the same as namespace or module name addition as a prefix. The scope of this is much smaller, and as far as your point goes, I completely agree. What you mention is a problem with e.g. Objective-C, but not with Swift. However, this is not the topic of this post. I’m talking about a situation where some module would have, for example, multiple screens like OnboardingWizardView, OnboardingWizardDetailsView etc. It’s convent to have their e.g. data source or some other component that they are using with the same prefix so you can easily find them, and show association and intent of use.

Leave a Reply

Your email address will not be published. Required fields are marked *