Naming Things (with notes)
0 likes57 views
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.
More Related Content
Similar to Naming Things (with notes) (20)
Recently uploaded (20)
![Formal Methods: Whence and Whither? [Martin Fr辰nzle Festkolloquium, 2025]](https://cdn.slidesharecdn.com/ss_thumbnails/mf2025-250305164811-a0930761-thumbnail.jpg?width=560&fit=bounds)
Naming Things (with notes)
- 2. @aupajo .co.nz Hi, Im Pete. Ive been writing Ruby for about 11 years, I work for a company called Trineo, and I live in New Zealand. Thats me squinting in the sun at RubyConf AU back in March.
- 4. What is code? Ostensibly for the computer. In reality, its 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 e鍖cient. By e鍖cient, I dont mean e鍖cient for the computer, I also mean e鍖cient for the human mind. To understand that, I want you to focus on an idea: cognitive overhead.
- 6. Why is naming things important? Its our primary tool for communication. It is the artefact left behind of someones 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 were 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. Di鍖culty comprehending indicates more clari鍖cation needs to be done.
- 8. VARIABLES
- 9. Who can tell me whats 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 cant 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.
- 18. Ah. Wouldnt 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 isnt meant to be an array, avoid numbers. This is a common pattern seen in tests.
- 24. This is better. Now youre articulating why you have two users: one is earlier and one is later.
- 25. Type su鍖xes 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 isnt useful.
- 27. These properties and methods return booleans. But you wouldnt 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. Its a bit like saying thing in English.
- 30. Better.
- 31. METHODS
- 32. Redundancy.
- 33. Better.
- 34. Repeated pre鍖xes in a method name or property name often indicate one thing
- 35. You found another object!
- 36. CLASSES
- 37. Pre鍖xes: not the worst thing, but consider why this happens. Its 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 鍖ags. 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. Heres 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 youre trying to achieve. This allows you to think more clearly about what is and isnt needed.
- 44. Speci鍖city is good, but use your judgement. For instance, its probably 鍖ne 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 speci鍖city.
- 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. Theyre unnecessary information that usually only adds cognitive overhead.
- 52. Better. The API is clear to use, and thats all that matters.
- 54. Directories and their structure are just as important as the 鍖le name. Both can add context and lower overhead for 鍖nding 鍖les or 鍖guring out where to place 鍖les. 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, its 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 softwares 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
- 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, re鍖ecting. 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-de鍖ned 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