Using the right names is an essential part of writing maintainable code. For a computer, any name will work just fine—they either match or not. For the humans who read the code, the names are the first thing they have in mind as they work on the . We all have some capacity to deal with a wrong name. If necessary, we can do a mental translation when the name doesn’t match the concept, or we can ignore some typos. But doing so uses both our memory and mental capacities. It’s easier and more efficient to work with the code that has the naming done right. code One name for one thing For organizing our stuff, the general advice is to have . Similarly, our lives will be much easier if all the people involved in the same project use the same terminology. Usually, we developers don’t have a perfect understanding of the domain in which the project is used. As a result, it makes the most sense to learn the terminology that is used by our business colleagues and use it in the code as well. a place for everything and everything in its place Parts of speech To create terminology that is easy to use, it makes sense to apply some of the grammatical knowledge we all got from school. Different types of words fit better in different use cases: Nouns are a perfect fit for objects or primitive values: , , user accountNumber customerEmail Adjectives work great for some Boolean flags: , allowed disabled Verbs match functions or object methods , user.login() shutDown() You’ll likely find cases where it would make sense to bend this rule, but for me, it makes sense to try tweaking the names to match this pattern. For example, for a method that checks the current state, I would use instead of . user.isActive() user.active() Avoid abbreviation I’m always skeptical of abbreviations as names in code. Many abbreviations are obvious only when you are deep in the . A reader who is new to the code and the domain can be confused. Making names short doesn’t improve meaningful metrics. When we write code, we usually use code suggestions, and most lines fit on the screen anyway. context of the code When there is a potential conflict between brevity and clarity, I always prefer to stay on the side of clarity. The only abbreviation I can think of now that I’m OK with seeing in the code is VAT. It’s so commonly used that it is easier to understand than its expanded form: . value-added tax Pronunciation All names we put to code are used in two ways. In writing—in code or documentation, and in speech—and when we talk about them, it’s important to think about both use cases when choosing the name. Pronunciation is often another reason to avoid abbreviations: they often miss vowels, and you may need to say it letter by letter. Avoid name collisions Try not to reuse the names with different meanings in other contexts. If you use some synonyms instead, then it will be easier for developers to intuitively understand the terms correctly when they hear them—without overthinking about the context in which they were used. Brainstorm ideas I have a high bar for naming things. Some names are easy to create; others are more difficult to come up with. For the most complicated cases, I try to write down as many ideas as I have in the ticket that will introduce a given concept to the code. I try to generate about 3 to 5 ideas—if it’s very difficult, I write down even the ones I don't like. With this in place, I ask my colleagues for their opinion. In this way, I get external input and spend more time on thinking about the name. It helps in making the decision. Newsletter If you want to get occasional emails about programming or related topics, you can . sign up for my newsletter here Also published . here

This story contains new, firsthand information uncovered by the writer.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Tips for Writing Maintainable Code: Naming Things

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

3 Steps to Adding End-to-end Tests to Your Project

104 Stories To Learn About Go

105 Stories To Learn About Functional Programming

100+ Free Pluralsight Courses to learn Python, Java, and Spring Boot

10 Websites to Learn JavaScript for Beginners

104 Stories To Learn About Programming Top Story

3 Steps to Adding End-to-end Tests to Your Project

104 Stories To Learn About Go

105 Stories To Learn About Functional Programming

100+ Free Pluralsight Courses to learn Python, Java, and Spring Boot

10 Websites to Learn JavaScript for Beginners

104 Stories To Learn About Programming Top Story

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps