Naming things in code
Posted on June 6th, 2009 in Castalia, Delphi | 7 Comments »
I came across a great blog post yesterday by Robert Nystrom, Naming Things in Code. Robert goes through a whole bunch of examples and comes up with some rules for how things should be named. Here’s a an oversimplification:
- Type names should be nouns
- Functions that do things should be verbs
- Functions that return booleans should be questions
- etc…
I don’t want to reproduce his article here. I want you to read his article.
I’ve thought for a long time that the way things are named in code is one of the most important decisions a programmer can make. I’ve also discovered that when you’re “in the flow” of creating something, stopping to decide the best name for something can be an interruption and can actually hurt your code.
Sometimes, you know you need to store some data in a temporary variable, for example, but you’re just not sure what to call it. So either you break your flow to stop and think up the right name, or you call your variable “X” and you move on.
This exact scenario is the reason that the first refactorings created in Castalia were the simple “rename” refactorings. In my opinion, the essence of refactoring comes down to two things: 1. Renaming things, and 2. Extract Method. The whole point of both of these is to take code that you know should be organized better and to make it really easy to organize it better.
So when you realize that X should really be called “AverageUnits,” you can use Castalia Refactorings to change it with just a few keystrokes and move on, with no tedium and with no impact on the way the code works.
The point? More readable code is better code.
7 Responses
I agree with most of that article, but I’m not sure on this one:
Bad: ConnectionManager
Good: Connection
The point of a class named with “Manager” or “Helper” is to show that this class manages something (usually a group of similar things). A ConnectionManager is not a connection itself in general. Perhaps it could be renamed “ConnectionPool” or “ConnectionQueue” to be more specific, but I don’t generally find “Manager” or “Helper” in names as being bad. What do others think on this? What would be the alternative name for something that I called “ConnectionManager” (let’s say it manages a list of connections.)
Btw, I completely agree about the refactoring points made here. It is often a good idea to look again at code you wrote and consider modifying the names you’ve chosen!
-MarkF
I used to make my Functions that return Booleans always be questions – but it was pointed out that in IF, WHILE, etc statements they then read a bit funny:
if Empty (Vector) then
Does read better thant:
if IsEmpty (Vector) then
However if it is a Method of Vector then:
if Vector.IsEmpty then
would be okay – so context is also important
In general “is” is not used to make it read as a proper sentence in statements, but to make it clear that we are not modifying the argument.
Empty(Vector)
Could be construed as a function that empties (clears) the Vector argument.
IsEmpty(Vector)
Makes it clear that we are just asking if the argument is empty. It becomes clear that this version won’t modify the argument (at least we hope!)
I have to agree with MarkF on the ConnectionMagaer thing. I don’t think it is a bad idea to call an object a manager if he manages some numer of objects.
can you make you code case insensitive.
in navigation toolbar I cannot see class function for “Form1″ if changed to “form1″….
[...] a friend’s blog (Jacob Thurman, author of the great Castalia IDE expert for Delphi) and found a post on a related topic: giving members descriptive names. His post has some great insight, but also links to a blog post [...]
@MarkF
It appears to me that Robert isn’t saying “don’t name it ConnectionManager”, he’s saying that from a design perspective Connections should manage themselves… which is an entirely different discussion than the current one.
I agree with you, if you have an object that manages connections then it’s probably best called ConnectionManager.
Of course thanks to Jacob, we can flip-flop on that decision as much as we want.