The document discusses the importance of naming in programming, emphasizing that good names help communicate intent and reduce cognitive overhead for developers. It explores common pitfalls in naming, such as ambiguity and redundancy, and offers solutions to improve clarity and efficiency in code. The author stresses that code should be readable and understandable for humans, as it ultimately serves as a bridge between human thought and computer execution.

2. @aupajo
.co.nz
Hi, I’m Pete. I’ve been writing Ruby for about 11 years, I work for a company called Trineo, and I live in New Zealand. That’s me squinting in the sun at RubyConf AU back
in March.

3. @aupajo
NAMING
THINGS

4. What is code?
Ostensibly for the computer. In reality, it’s a recipe that has to be digested by two audiences: the computer and the developers. You have to encode behaviour and intent.

5. What is good
code?
Good code is efficient. By efficient, I don’t mean efficient for the computer, I also mean efficient for the human mind. To understand that, I want you to focus on an idea:
cognitive overhead.

6. Why is naming
things important?
It’s our primary tool for communication. It is the artefact left behind of someone’s thoughts and intentions. A good name conveys how to use something and give you a
clear sense of when it should change.

7. Why is naming
things hard?
Often because when we’re forced to pick a name, we have to articulate a concept. Often it is hard to express a concept in a simple word or two. Ideas can be subtle.
Struggling to name something is an important part of of design. Difficulty comprehending indicates more clarification needs to be done.

8. VARIABLES

9. Who can tell me what’s wrong here?

10. Remove all ambiguity about units!

11. No context. Hard to search for.

12. Some developers solve this problem with comments. But why is it you have to explain the code? Why can’t the code explain itself?

13. Better. But elapsed time for what?

14. Best. The context is clear.

15. What does this code do?

16. Nothing has changed but for your ability to understand this code. To the computer, these expressions are identical. But everything important to you, the developer, has
changed.

17. Flagged for what?

18. Ah. Wouldn’t want to mistake that one.

19. Abbreviations are hard to read. Why `res` instead of `response`?

20. Better.

21. Creates confusion. Did the author intend an array here?

22. If it is meant to be an array, let it be an array.

23. If it isn’t meant to be an array, avoid numbers. This is a common pattern seen in tests.

24. This is better. Now you’re articulating why you have two users: one is earlier and one is later.

25. Type suffixes usually add more context than is necessary, and cause greater churn when you replay one type for another (bigger concern in a dynamic language).

26. Better. We discarded information that probably isn’t useful.

27. These properties and methods return booleans. But you wouldn’t know it to look at them.

28. Better.

29. Be careful of words like “info” and “data”. What do they mean? Are these all equivalent. It’s a bit like saying “thing” in English.

30. Better.

31. METHODS

32. Redundancy.

33. Better.

34. Repeated prefixes in a method name or property name often indicate one thing…

35. You found another object!

36. CLASSES

37. Prefixes: not the worst thing, but consider why this happens. It’s because the author wanted to use the name “File” twice. Consider what would happen if they were
forced to pick another name.

38. Better.

39. Perhaps this also hints at an object though?

40. These names are red flags. Why?

41. What does a “page manager” do? Any guesses? Well, it manages a page. So anything that could plausibly be considered “managing a page” could easily get added to
this class. These classes quickly balloon out of control.

42. Here’s an example. Imagine you have a “page formatter”.

43. By turning this into a formatted page, you are now talking about the end result of what this class does – what you’re trying to achieve. This allows you to think more
clearly about what is and isn’t needed.

44. Specificity is good, but use your judgement. For instance, it’s probably fine to call a postal address simply an “address”.

45. However, if your application deals with more than one type of address, you may want to consider increasing its specificity.

46. CONVENTIONS

47. These methods invite confusion, because you constantly have to ask yourself “is this object add, insert, or append”?

48. Here, never have to think.

49. Always consider your domain. For instance, does your business sell to “users”?

50. Probably not. You should be able to speak the language of the domain.

51. Avoid patterns in names. Design patterns are implementation details, and encoding the pattern into the name prevents altering that class in the future to not use that
pattern. They’re unnecessary information that usually only adds cognitive overhead.

52. Better. The API is clear to use, and that’s all that matters.

53. NAMING
ERGONOMICS

54. Directories and their structure are just as important as the file name. Both can add context and lower overhead for finding files or figuring out where to place files. A well-
named directory can be more powerful than a well-named class.

55. Consider the ergonomics. Folders with too many items take longer to read. A folder with one item is like having a category with one item, which is not a useful category
to have.

56. Long names are bad, because they often contain too many concepts, indicating an object that has a high cognitive overhead.

57. They also lead to abbreviations, because typing out “bookings_products_vehicle_types” everywhere is cumbersome. (This is a real world example.)

58. If necessary, make the name longer. Brevity is good, but the ultimate goal is clarity. Here, the key concept is that we have vehicle types.

59. When the inevitable shortening happens, it’s easier to do things like this. Not perfect, but far better than “bpvt”.

60. Beware of names that vary in small ways. They can easily be confused.

61. What is it you do?
You are a translator for two audiences. You are the bridge between the human and the computer. You need to know how computers work and how humans work – both
the humans which your software serves, and the humans which your software will by changed by. Your primary weapon in your toolbox against ambiguity and cognitive
overhead – the forces that corrode a software’s maintainability – is to name. You name things every day. Be mindful about the words you choose. Software should be
written to be read by another developer.

62. Programs must be written
for people to read, and
only incidentally for
machines to execute.
“
Harold Abelson
Structure and Interpretation of
Computer Programs

63. @aupajo
Slides twitter.com/aupajo
Thank you.

65. The ratio of time spent reading
versus writing is well over 10 to 1.
We are constantly reading old
code as part of the effort to
write new code.
Making it easy to read makes it
easier to write.
Robert C. Martin
“Uncle Bob”

66. The ratio of time spent reading
versus writing is well over 10 to 1.
We are constantly reading old
code as part of the effort to
write new code.
Making it easy to read makes it
easier to write.
Robert C. Martin
“Uncle Bob”

67. The ratio of time spent reading
versus writing is well over 10 to 1.
We are constantly reading old
code as part of the effort to
write new code.
Making it easy to read makes it
easier to write.
Robert C. Martin
“Uncle Bob”

68. A parable about
stones
Marco Polo describes a bridge, stone by stone. "But which is the stone that supports the bridge?"
Kublai Khan asks. "The bridge is not supported by one stone or another," Marco answers,
"but by the line of the arch that they form.” Kublai Khan remains silent, reflecting. Then he adds:
"Why do you speak to me of the stones? It is only the arch that matters to me.” Polo answers: "Without stones there is no arch."

69. On Exactitude
To my mind exactitude means three things above all:
(1) a well-defined and well-calculated plan for the work in
question;
(2) an evocation of clear, incisive, memorable images;
(3) a language as precise as possible both in choice of
words and in expression of the subtleties of thought and
imagination.
- Italo Calvino