#[1]Neil Kakkar
[2][Neil-obscure.jpeg] [3]Neil Kakkar
[ ]
[4]About[5]Blog[6]Shorts
You might also like
* [7]All Stories Are Wrong, but Some Are Useful
* [8]Equivalent Salary Calculator By City
* [9]10 Powerful Life Skills for the New Decade
* [10]Is That the Right Sequence to Do Things In?
Subscribe to the Idea Muse
One idea every week designed to make you smarter. Join 1,300+ people cutting
through the noise. [11]Read more
Email Address * ____________________
First Name * ____________________
____________________
Subscribe
Why Is Naming Things Hard?
Feb 16, 2021 • [12]Tech
An interesting shift happens once you realise you’re writing code for
humans to read, and not just for machines to execute.
One big change is that writing clearly takes priority over correct
code.^[13]1
Reading code involves building up a mental model of what each thing
should do, and how these things interact with each other. The best
code, however, short-circuits reading everything. Instead of reading
the implementation, you use variable and function names, comments, and
other clues to figure things out.^[14]2
This is chunking. You combine things together, and remember them
together. For example, a Chess Opening, like the Queen’s Gambit, is a
chunk. So is a forEach loop: just by the name, you can figure out that
it’s going to do something to every element of an array.
Once you’ve built a chunk for a forEach loop, you don’t have to read
the implementation of forEach to understand what it will do. This is
very powerful, since it allows you to come back to the code, without
having to read the implementation of everything again.
Thus, a good name is a chunk that encodes important information about
what the thing does.
We’re compressing information into the name. This is almost always a
lossy compression. Further, the more lines to compress, the more losses
you incur, since you want your names to be no longer than 80
characters.
The goal of good naming is to minimize this loss.
And naming things is hard because of this compression. English isn’t
precise like C++, so compressing from a precise to an ambiguous
language increases losses. Another big reason is that choosing the most
important things to include is hard. You’ll notice that most
disagreements about naming fall on these two axes: either the name
isn’t just right for what you want to do (does it assign or setup or
link or mangle?). Or the name doesn’t capture important parts of the
functionality.
I think this is the generating function for most best practices I’ve
heard of, and thus lots more valuable than one specific guidance.
Generating best practices
1. Make functions do one thing
When a function does multiple things, the name needs to encode lots
more information, like
link_user_to_trial_and_enable_downloads_and_set_charge_date().
That’s a long name, and a sign of losing too much information: what
semantics should the name expose about the charge date, and
enabling downloads?
These side effects are hard to encode for in the name.
2. Keep functions small
Long functions, like functions doing lots of things, need to encode
lots of information into the name. And since the name length is
bounded, you lose a lot more information in compressing this long
name, which leads to poorer names.
3. Avoid meaningless names
Since we’re writing code to be read by humans, names that don’t
compress any information don’t help us build chunks. This makes it
harder to read, since you have to go down one layer of abstraction.
You need to parse the implementation to understand what that piece
of code does.
4. Avoid too abstract names
do_things() is a suitable name for any function, but the
compression is too lossy to be useful - you lose almost all
information, and need to parse the body to figure out what it does.
Not great. It’s almost a meaningless name.
5. Be consistent
When you build similar chunks throughout your code base, it becomes
easier to go up another layer of abstraction, by chunking the
chunks. For example, continuing the trial management system
example, you’ll have 3 things in place:
1. link_user_to_trial_agreement_given_email()
2. enable_research_downloads_for_user()
3. set_charge_date_for_user()
Since they’re operating in the same domain, you can go up one level
to setup_user_for_trial() that does all three.
Disrupting best practices
The generator of best practices allows you to reason about cases where
best practices aren’t the best way forward.
For example, consider being consistent, and naming variables using
camelCase. Your entire codebase uses camelCase. You’re writing a new
function that’s very non-standard. It does arcane stuff that doesn’t
fit into your existing model. You need it, because legacy
integration/business requirements/etc. In effect, you don’t want anyone
to gloss over it when they read it.
So, do you stay consistent, and keep it in camelCase? Or, do you switch
to snake_case?
The goal is to keep things clear. I would switch to snake_case to show
how it’s different from the rest, and have some comments explaining the
arcane things it does.^[15]3
Precision with words
Spoken languages are very imprecise. There’s lots of ambiguity, double
meanings, and sentences that don’t mean anything.
Code, however, needs to be precise. Like we saw above, this is a source
of trouble, since we’re trying to compress a precise language into an
imprecise one, which makes searching for the right English words
harder.
These ideas apply to naming things outside of code, too! When you have
a name for something, it suddenly becomes legible.
Consider: You see some people around you who test if they can do
something once, and drop it if they fail. Some others keep trying until
they learn how to do it. The first group prizes its intelligence, while
the second group prizes its hard work. Then, when you hear about the
[16]Fixed vs Growth mindset, things immediately click.
Choosing the right name here is hard too. Every best practice that lost
its nuance over time can be attributed to a name that didn’t encode the
necessary information. People passed these ideas on without explaining
the nuances.
Or, consider equating two names. “Abortion is murder” - equating two
names that aren’t the same creates an interesting dynamic between
emotions and the truth. Each name has different connotations, and on
combining them together, you’re passing on the connotations of one onto
the other. This isn’t necessarily a good thing. You have to be very
careful of the equality operator in an imprecise language.
Conclusion
Optimise for clear, easy to understand code. The cost of reading it is
higher than the cost of executing it.
To do this, leverage chunking: write names that are meaningful, and
encode as much information as possible into the name.
However, writing meaningful names is a lossy compression. Every naming
maxim follows from minimising this loss.
And finally, the same idea applies to naming things in the real world.
Except, it’s even harder, since it’s encoding from an imprecise to
another imprecise language. Code, atleast, was unambiguous in its
execution.
Thanks to Soumya for reading drafts of this.
Have feedback? You can [17]reply to this post on Twitter.
1. You might contest this, that correctness comes first, but if it’s
clear to read, PR reviews will catch correctness bugs quickly. Or,
if no-one catches mistakes, and then things break, it’s easier for
your colleagues to fix things if they can read your code clearly.
Footnote to footnote: This is an instance of [18]taking ideas
seriously. [19]↩
2. Sometimes, poor naming gets in the way, generating an incorrect
model of how things work. Here, you have no choice but to read the
implementation. [20]↩
3. Ideally, you’d fix things properly so there isn’t a need for
something like this. But, the default is to have things like these
littered over a huge codebase. [21]↩
You might also like
* [22]All Stories Are Wrong, but Some Are Useful
* [23]Equivalent Salary Calculator By City
* [24]10 Powerful Life Skills for the New Decade
* [25]Is That the Right Sequence to Do Things In?
Subscribe to the Idea Muse
One idea every week designed to make you smarter. Join 1,300+ people cutting
through the noise. [26]Read more
Email Address * ____________________
First Name * ____________________
____________________
Subscribe
__________________________________________________________________
* Neil Kakkar
* Write (Code). Create. Recurse.
* [27]neil@neilkakkar.com
I want to understand how the world works. This blog tracks my growth,
the things I've learned, and how I'm leveraging them to do epic things.
*
*
*
*
*
References
Visible links
1. https://neilkakkar.com/feed.xml
2. https://neilkakkar.com/
3. https://neilkakkar.com/
4. https://neilkakkar.com/about/
5. https://neilkakkar.com/blog/
6. https://neilkakkar.com/shorts/
7. https://neilkakkar.com/story-of-stories.html
8. https://neilkakkar.com/salary-calculator-by-city.html
9. https://neilkakkar.com/powerful-life-skills.html
10. https://neilkakkar.com/sequencing-things-in-the-right-order.html
11. https://neilkakkar.com/subscribe
12. https://neilkakkar.com/categories/#Tech
13. https://neilkakkar.com/why-is-naming-things-hard.html#fn:1
14. https://neilkakkar.com/why-is-naming-things-hard.html#fn:3
15. https://neilkakkar.com/why-is-naming-things-hard.html#fn:2
16. https://neilkakkar.com/story-of-stories.html#the-story-of-growth-vs-fixed-mindset
17. https://twitter.com/neilkakkar/status/1361611070331305986
18. https://neilkakkar.com/taking-ideas-seriously.html
19. https://neilkakkar.com/why-is-naming-things-hard.html#fnref:1
20. https://neilkakkar.com/why-is-naming-things-hard.html#fnref:3
21. https://neilkakkar.com/why-is-naming-things-hard.html#fnref:2
22. https://neilkakkar.com/story-of-stories.html
23. https://neilkakkar.com/salary-calculator-by-city.html
24. https://neilkakkar.com/powerful-life-skills.html
25. https://neilkakkar.com/sequencing-things-in-the-right-order.html
26. https://neilkakkar.com/subscribe
27. mailto:neil@neilkakkar.com
Hidden links:
29. https://neilkakkar.com/why-is-naming-things-hard.html
30. https://github.com/neilkakkar
31. https://www.linkedin.com/in/neilkakkar
32. https://www.twitter.com/neilkakkar
33. https://medium.com/@neilkakkar
34. https://neilkakkar.com/feed.xml