Naming Things (with notes)

There's an old joke that goes, “The two hardest things in programming are cache invalidation, naming things, and off-by-one errors.” In this talk, we'll discuss the subtle art of naming things – a practice we do every day but rarely talk about.

Transcript

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