Code Craft: Tame the Name

[article]

I know that naming bears repeating.

But it's not enough to repeat the obvious. Developing good naming skills takes practice. Thankfully, writing code affords us many opportunities to practice the naming technique. What should I call this thing? Better question: What is it I'm creating? Indeed, there's a parallel between choosing good names and test-first development: They both force you to think before you code. Whenever I'm unsure what to call something, I find it beneficial to take my hands off the keyboard to think of a good name before the moment passes me by. It's in that quiet moment that I consider whether the name is pronounceable, expressive, and contextual-the three basic qualities of a good name.

What Did He Say?
One effective way to write code for humans to read is to choose names that you, a human, can pronounce...in public. It's a basic litmus test that often has surprising results. For example, you're bound to raise a few eyebrows if you walk about the office talking about the frgnky variable. Usually buying a vowel or two (foreignkey) does wonders for your pronunciation. The code will thank you, too.

What Did He Mean?
Good names are expressive, but they need not be verbose. A person who practices the coding craft learns how to strike a balance to come up with a name that's clear and concise.

Choose class names that express the purpose of the class as a noun or noun phrase. The CalcLifeExpAndPrem class, for example, was likely a function in its previous life.

It often helps to write a sentence describing the class, and then pick nouns you thought of when you weren't thinking of code. When it comes to code, we programmers tend to have an expanded vocabulary and we're quick to show it off. For example, our first thought might be to rename the class as CalcSessionFacadeEJB. Unfortunately, the name primarily describes the design pattern and technology used at the time the class was born (modern-day Hungarian notation) but says nothing about the class's purpose in life. Simply calling it a LifeInsuranceCalculator and placing the class in an appropriate package reveals its purpose, while not exposing the secrets of its inner workings. The new name also makes the class a beacon of refuge for wayward functions. And when it's no longer cool to be named after a pattern, the class won't be relentlessly teased by its peers.

Choose method names that use a verb phrase to describe what the method does, not how it does it. This implies that you know what the method will do before choosing a name. This is a good thing. If you pick a name before thinking through the method's purpose, you usually end up with a generic method name such as doIt() or process(). Methods with these ambiguous names lack cohesion and become dumping grounds for stray bits of code. You can go overboard by being too descriptive, as in the case of the sortMessageListByNameForDisplay() method. It's expressive, but un-clear because it leaves us with a question: What happens if we call it but we don't display the sorted message list?

Variables should describe the data they hold or the object they reference. If variables don't help you remember what they represent, then they need to be renamed. Two confused variables, actn and actno, were once found wandering aimlessly. When questioned, they responded that they represented "action" and "account number," respectively. At least their creator knew what they meant, right up until he went insane.

What Was He Thinking?
Context matters when it comes to

About the author

Mike Clark's picture Mike Clark

Mike Clark is the author of Pragmatic Project Automation (published in 2004) by The Pragmatic Bookshelf, editor of PragmaticAutomation.com, and the creator of several popular open source tools. Mike helps teams build better software faster through his company, Clarkware Consulting Inc.

AgileConnection is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!

Upcoming Events

Nov 09
Nov 09
Apr 13
May 03