The document discusses the importance of naming in coding, emphasizing that good names enhance communication between developers and computers while reducing cognitive overhead. It highlights the challenges of selecting appropriate names and the impact of ambiguity on code readability and maintainability. Additionally, it advocates for specificity, clarity, and understanding the domain language to improve code design and structure.

1. Naming Things
A Definitive Guide to
Nem Nomen
Nemonclatuer

2. 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.

3. 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.

4. 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.

5. 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 actually an important part of of design. Difficulty indicates that the object is doing too much.

6. Variables

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

8. Remove all ambiguity about units!

9. No context. Hard to search for.

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

11. Better. But elapsed time for what?

12. Best. The context is clear.

13. What does this code do?

14. 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.

15. Flagged for what?

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

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

18. Better.

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

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

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

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

23. 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).

24. Better.

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

26. Better.

27. Methods

28. Redundancy.

29. Better.

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

31. You found another object!

32. Classes

33. 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.

34. Better.

35. Perhaps this also hints at an object though?

36. These names are red flags. Why?

37. 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.

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

39. 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.

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

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

42. Conventions

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

44. Here, never have to think.

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

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

47. 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.

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

49. Naming ergonomics

50. 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.

51. 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.

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

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

54. 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.

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

56. If you have a term that can be taken multiple ways, that constitutes a pun. A “List” may be an type of object in your system, a “BucketList” may mislead a developer into
thinking it is a type of “List”, when in fact you meant something entirely different.

57. Better.

58. 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.

59. “Indeed, 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. ...[Therefore,]
making it easy to read makes it easier to write.”
– Robert C. Martin (Uncle Bob)

61. 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."

62. 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