There are only two hard things in Computer Science: cache invalidation and
naming things
– Phil Karlton
The importance of properly naming classes, functions and variables is often
overlooked. Yet doing it well can greatly enhance the readability of code.
I believe there are 2 main reasons why this is so hard:
Most programmers tend to be “left-brainers”. Thus they tend to be more
interested in solving logical puzzles. We’re excited to start solving a problem
and tend to neglect thinking of proper names.
When you’re having a hard time naming your functions, it could be an indicator
that something is wrong in the design of your application.
I’m going to focus on the first reason here, because the second would be a bit
too broad to cover in a single blog post.
You can find a lot of concrete tips online or in books. However, I want to give
some more generic advice here, so you can get a better feel for why these tips
work.
Let’s take an obvious and exaggerated example of bad naming:
# Bad
class Thing
attr_reader :arr
def initialize(arr)
@arr = arr
end
def do_stuff(val)
arr.keep_if do |a|
a.include?(val)
end
end
end
t = Thing.new(['John', 'Jane', 'Carl'])
p t.do_stuff('o')
# Good
class NameArchive
attr_reader :names
def initialize(names)
@names = names
end
def names_with_letter(letter)
names.keep_if do |name|
name.include? letter
end
end
end
archive = NameArchive.new(['John', 'Jane', 'Carl'])
p archive.names_with_letter('o')
The first example hides the meaning of the code. If complex code would use names
like this, it would only be readable by the computer, or the person who wrote it
(at least until he/she has to look back at it the next day/week/month).
The second example is easier to read and understand, because it reaches the goal
of proper naming, which is to clearly express the intent of the code.
Luckily most programmers quickly get a basic level of proficiency in naming and
quit bad habits like naming a variable array.
These were very basic examples though. Consistently coming up with good names
becomes a bit trickier when working on large projects, so here are some tips:
Look up the words!
This counts for classes, functions and variables: If you’re having a hard
time finding a good name, look it up in a dictionary. If you have a name,
but it doesn’t feel quite right, then look up some related words on a site
like Thesaurus.
These days it’s very easy to just check a definition or a related word, so
use it to your advantage. This is especially important if your native
language isn’t English.
Naming classes
Most classes can be named pretty easily by using nouns from the use case
(eg. “The User can create a Post”).
When this doesn’t work, like when you’re working on something more abstract,
then its time to turn to google or the dictionary for inspiration.
If you think your class name isn’t detailed enough, then don’t try to solve
it by using generic terms like Manager or Data.
Naming functions
Make sure your function does one thing, and its name should describe that
one thing in a clear way. Try to keep the function name concise, but don’t
make it any shorter than it needs to be to stay descriptive.
If you’ve spent some time finding a good name for a function and it still
doesn’t feel right, then it may be sign that the function belongs in another,
probably still-to-be-created, class.
Naming variables
Use clear variable names to indicate their content, but try to keep them
short. A good rule of thumb is to keep them as short as possible without
hiding their meaning in their context.
For example, you don’t have to go and replace i with index in your
for loops. Using i in loops has become convention and doesn’t require a
longer name to be clear.
I hope this has made you a bit more aware of the importance of naming things.
I think it’s a skill that’s often overlooked and takes a bit of persistence to
get better at.
If you have written classes with some obscure variable names, then next time
take a minute to think of, look up or even invent a good name before you
start coding furiously. Unless, of course, you want to write unmaintainable
code.