GOPHERSPACE.DE - P H O X Y
gophering on 1436.ninja
   #[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