How to name things: the hardest problem in programming

3dc8723d06d8e0cafbb1c78ea42dfe6a?s=47 Peter Hilton
December 15, 2017

How to name things: the hardest problem in programming

Developers can get better at their craft by learning from the great writers who mastered theirs. Writing software isn’t the same as writing a novel, but there are parallels. Besides, advice from writers is better because writers have been struggling with their craft for many centuries, not just a few decades. It’s better-written as well. This talk shares great writers’ best advice for coders: Stephen King on refactoring, Anne Rice on development hardware, Hemingway on modelling with personas, and Neil Gaiman on everything.

This session first explores the similarities between writing and coding, and uses writers’ advice to identify different kinds of avoidable bad naming in code. Some class, method, and variable names are so bad that they’re funny, but you’ve still seen them in production code. The second part of the session explores practical techniques for working on better naming, including renaming things. Renaming is even harder because it includes naming things plus other hard things. The final section goes back to writing. The next step after finding better names in code is to write better comments in code, which is almost as hard as naming is.

The surprising thing about naming things well in code is not that it’s hard, but how easy it is to accept bad names. This is a hard problem that’s worth working on, because although you can’t make the naming problem go away, you can learn to write much better code regardless of which technologies you use.

3dc8723d06d8e0cafbb1c78ea42dfe6a?s=128

Peter Hilton

December 15, 2017
Tweet

Transcript

  1. 2.

    Phil Karlton on naming @PeterHilton • 2 ‘There are only

    two hard things in Computer Science: 
 1. cache invalidation and 2. naming things.’ http://hilton.org.uk/blog/why-naming-things-is-hard 0. off-by-one errors
  2. 4.

    Stephen King on pair programming ‘Write with the door closed,

    
 rewrite with the door open.’ 5 @PeterHilton •
  3. 5.

    Anne Rice on development hardware ‘I find the bigger the

    monitor, 
 the better the concentration.’ 7 @PeterHilton •
  4. 6.

    Ernest Hemingway on user personas ‘When writing a novel a

    writer should create living people; 
 people not characters. 
 A character is a caricature.’ X @PeterHilton •
  5. 7.

    W. Somerset Maugham on enterprise architecture ‘There are three rules

    for writing the novel. Unfortunately, no one knows what they are.’ X @PeterHilton •
  6. 9.

    Neil Gaiman on productivity ‘Write. ‘Put one word after another.

    
 Find the right word, put it down. ‘Finish what you’re writing. Whatever you have to do to finish it, finish it.’ X @PeterHilton •
  7. 10.

    Neil Gaiman on code review ‘Put it aside. Read it

    pretending you’ve never read it before. Show it to friends whose opinion you respect’ X @PeterHilton •
  8. 11.

    Neil Gaiman on review feedback ‘When people tell you somethings

    wrong or doesn’t work for them, they are almost always right. ‘When they tell you exactly what they think is wrong and how to fix it, they are almost always wrong.’ 9 @PeterHilton •
  9. 12.

    Neil Gaiman on continuous delivery & refactoring ‘Fix it. ‘Remember

    that, sooner or later, before it ever reaches perfection, you will have to let it go and move on and start to write the next thing. ‘Perfection is like chasing the horizon. Keep moving.’ X @PeterHilton •
  10. 13.
  11. 14.

    Neil Gaiman on open source ‘The main rule of writing

    is that if you do it with enough assurance and confidence, you’re allowed to do whatever you like.’ X @PeterHilton •
  12. 15.

    Summary of advice from writers Advice from writers is useful,

    and 
 not only about naming Writers have been at it for centuries; programming is merely decades old. Also, their advice is better written. And funnier. X @PeterHilton •
  13. 18.

    What is above all needed is to 
 let the

    meaning choose the word, 
 and not the other way around. … the worst thing one can do with words is surrender to them.
  14. 19.

    When you think of a concrete object, you think wordlessly,

    and then, if you want to describe the thing you have been visualising you probably hunt about until you find the exact words that seem to fit it.
  15. 20.

    When you think of something abstract you are more inclined

    to use words from the start, and unless you make a conscious effort to prevent it, the existing dialect will come rushing in and do the job for you, at the expense of blurring or even changing your meaning…
  16. 21.

    1. Never use a metaphor, simile, or other figure of

    speech which you are used to seeing in print. 2. Never use a long word where a short one will do. 3. If it is possible to cut a word out, always cut it out. 4. Never use the passive where you can use the active. 5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. 6. Break any of these rules sooner than say anything outright barbarous.
  17. 22.

    These rules sound elementary, and so they are, but they

    demand a deep change of attitude in anyone who has grown used to writing in the style now fashionable. Politics and the English Language, George Orwell (1946)
  18. 23.

    1. ‘Never use a metaphor, simile, or other figure of

    speech which you are used to seeing in print’ (beware of over-using design patterns, and using their names just because you’re used to seeing them in code) e.g. AbstractConfigurationFactory X @PeterHilton •
  19. 24.

    2. ‘Never use a long word 
 where a short

    one will do’ (prefer concise variable names, 
 use longer names for a good reason) e.g. company_person_collection vs staff X @PeterHilton •
  20. 25.

    3. ‘If it is possible to cut a word out,

    always cut it out’ (avoid additional words that don’t add any meaning to a name) e.g. AbstractObjectFormatterProxy … X @PeterHilton •
  21. 26.

    4. ‘Never use the passive 
 where you can use

    the active’ (respect grammatical rules for identifiers) e.g. class PlanEvents vs class EventPlanner or even class Scheduler X @PeterHilton •
  22. 27.

    5. ‘Never use a foreign phrase, a scientific word, or

    a jargon word if you can think of an everyday (don’t let technical jargon from a library pollute your domain model) (beware libraries that import ‘foreign’ naming from one language to another) e.g. ShipmentMonad X @PeterHilton •
  23. 28.

    6. ‘Break any of these rules sooner than say anything

    outright barbarous’ (don’t blame me if your code is featured on The Daily WTF) Note: a lot depends on context; publishing library code is not the same as maintaining private application code X @PeterHilton •
  24. 30.

    Lewis Carroll on bad naming ‘When I use a word,’

    Humpty Dumpty said, in rather a scornful tone, ‘it means just what I choose it to mean - 
 neither more nor less.’ Through the Looking-Glass, & What Alice Found There (1871) 18 @PeterHilton •
  25. 31.

    Deliberately meaningless names In theory, foo is only used as

    a placeholder name 
 (because it doesn’t mean anything) 19 @PeterHilton •
  26. 32.
  27. 33.

    What is the worst ever variable name? data What is

    the second-worst name? data2 What is the third-worst name ever? data_2 X @PeterHilton •
  28. 34.

    Abbreviations are ambiguous Is char a character or characteristic? Does

    mod mean modify or modulo? What about acc, pos or auth? Sadly, fab is probably a function ƒ:A➞B
 (not fabulous) 22 @PeterHilton •
  29. 35.

    One letter is too short Local variable: what is the

    meaning? const a = 42; The exception that proves the rule? for (int i = 1; i < 42; ++i) 23 @PeterHilton •
  30. 36.

    One letter is too short for type names as well

    (unless you write extensive comments!) def modp[C]
 (f: B1 㱺 (B2, C), a: A1): (A2, C) = { val (b, c) = f(get(a)) (set(a, b), c) } https://github.com/scalaz/scalaz/blob/series/7.2.x/core/src/main/scala/scalaz/Lens.scala 24 @PeterHilton •
  31. 37.
  32. 39.
  33. 41.
  34. 42.

    Multiple words can be replaced by more specific words What’s

    an appointment_list? a calendar What’s an company_person? an employee or perhaps an owner What’s a text_correction_by_editor? just an edit X @PeterHilton •
  35. 43.

    Multiple meaningless words are meaningless Formatter ObjectFormatter AbstractObjectFormatterProxy ‘This is

    like homeopathy. What you’ve done is you’ve diluted the meaning until it’s all gone.’ @KevlinHenney 28 @PeterHilton •
  36. 44.

    Vague words are vague Alan Green wrote* about vague words,

    e.g. InvoiceManager TaskManager ‘Manager’ is imprecise. One of its many meanings may be the word you want: Bucket, Supervisor, Planner, Builder * http://www.bright-green.com/blog/2003_02_25/naming_java_classes_without_a.html 29 @PeterHilton •
  37. 45.

    Vague words are vague 30 @PeterHilton • get at the

    start of a method name is
 appropriate only for returning a field value. If it does anything else, or gets the data from anywhere else, use another name: fetch, find, lookup, create, calculate, derive, concoct, transmogrify
  38. 46.

    JavaBeans Specification (1996/1997) JavaBeans taught a generation of Java programmers

    to break object encapsulation and use vague method names. These bad habits are still with us. Stop writing getters! What libraries are you using that still actually require JavaBeans properties defined by get and set methods? X @PeterHilton •
  39. 47.

    private boolean isValid; // ! WRONG! private final boolean valid;

    // " // JavaBeans property named ‘valid’. public isValid() { return valid; }
  40. 48.
  41. 49.

    Wrong words are wrong, synonyms are confusing order ≠ shipment

    carrier ≠ broker shipment ≠ transport leg shipment = consignment carrier = transporter transport leg = journey X @PeterHilton •
  42. 51.

    // Not enough jokes in code /** Configure and start

    Apache Camel. */ { Logger.info("Starting Camel…") val context = new DefaultCamelContext() configuredRoutes foreach { route => 
 context.addRoutes(route)
 } context.start() } def mountCamel() {
  43. 52.
  44. 53.

    Summary of naming things badly Meaningless: foo Too general: data

    Too short: a Too long: text_correction_by_editor Abbreviated: acc Vague: InvoiceManager Wrong: order Not funny: startCamel X @PeterHilton •
  45. 55.

    Sam Gardiner on naming ‘If you don’t know what a

    thing should be called, 
 you cannot know what it is. If you don’t know what it is, you cannot sit down 
 and write the code.’ http://97things.oreilly.com/wiki/index.php/ A_rose_by_any_other_name_will_end_up_as_a_cabbage X @PeterHilton •
  46. 56.

    How to solve the naming problem 1. Improve your vocabulary.

    2. Adopt better naming practices. 3. Use naming guidelines. 33 @PeterHilton •
  47. 57.

    Become a better writer Naming is just one part of

    writing, and is mostly about vocabulary. You may remember working on vocabulary as part of learning a foreign language. Not having had to learn a foreign language is a mixed blessing. 34 @PeterHilton •
  48. 58.

    Improve your vocabulary Read books, especially funny novels,
 or whatever

    you can’t stop reading. Play word games with someone who always wins, 
 until they don’t. 35 @PeterHilton •
  49. 59.
  50. 61.
  51. 63.

    @PeterHilton • 38 A sandwich walks 
 into a bar.

    The barman says, ‘I’m sorry, 
 we don’t serve food.’
  52. 64.

    Tell jokes Many jokes rely on word-play. It takes practice

    to think of puns quickly. Puns are important for naming, 
 because they rely on double-meanings. Spotting double-meanings is the essential skill for avoiding ambiguous names. 39 @PeterHilton •
  53. 65.

    Learn domain-specific vocabulary Scan the domain model entities’ Wikipedia pages

    for names of related concepts. Read novels set in your customer’s domain, to learn their jargon. Find out what they really mean. 40 @PeterHilton •
  54. 66.

    Adopt better naming practices 1. Start with meaning and intention.

    2. Use words with precise meanings. 3. Prefer fewer words in names. 4. No abbreviations in names (except id) 5. Use code review to improve names. 6. Read the code out loud to check that it sounds okay. 7. Actually rename things. X @PeterHilton •
  55. 67.

    Adopt better naming practices 1. Use words with precise meanings.

    2. Adopt naming guidelines. 3. Use code review to improve names. 4. Read the code out loud to check that it sounds okay. 5. Don’t expect to get the perfect name at first 6. Actually rename things. 41 @PeterHilton •
  56. 68.

    Replace vague words with more specific synonyms Manager Object Data

    Thing Info Amount Details
 do execute perform operate manage handle X @PeterHilton •
  57. 69.

    Overcome fear of renaming The only thing harder than naming

    is renaming. Renaming requires change, a conversation, and new understanding. ‘Rename’ is the safest but most effective refactoring. Use it. 43 @PeterHilton •
  58. 71.

    Use dictionary words Only use correctly-spelled dictionary words and abbreviations

    that appear in a dictionary. Make exceptions only for id and
 documented domain-specific language/abbreviations. ☹ acc, pos, char, mod, auth, appCnt Remember: abbreviations are always ambiguous 45 @PeterHilton •
  59. 72.

    Expand single-letter names Don’t make exceptions to using dictionary words

    for 
 single-letter names. Use searchable names. ☹ i, j, k, l, m, n, t, x, y, z And before you ask about loop counters i in for loops, 
 tell me why you are still using for loops in 2017! 46 @PeterHilton •
  60. 73.

    Articulate symbolic names Don’t use ASCII art symbols instead of

    words. Programmers who encounter symbolic names in libraries invent names based on what the symbol looks like. ☹ >=>, fish ☹ <*>, spaceship $ ??? 47 @PeterHilton •
  61. 74.

    Limit name character length Keep name length within a twenty

    character maximum. ☹ ForeignDomesticAppleCount ‘good naming limits individual name length and reduces the need for specialized vocabulary’ Achieving Software Quality through Source Code Readability, Phillip Relf (2004) 48 @PeterHilton •
  62. 75.

    Limit name word count Keep name length within a four

    word maximum, and avoid gratuitous context. Limit names to the number of words that people can read at a glance. ☹ newRedAppleSizeType, myAppSizeType Achieving Software Quality through Source Code Readability, Phillip Relf (2004) 49 @PeterHilton •
  63. 76.

    Describe meaning Use a descriptive name whose meaning describes a

    recognisable concept, with enough context. Avoid placeholder names that deliberately mean nothing more than a_variable. ☹ foo, blah, flag, temp In code review, ask, ‘What is a Foo?’ 50 @PeterHilton •
  64. 77.

    Choose concrete words Use words that have a single clear

    meaning. Abstract words might apply equally to multiple identifiers. ☹ Manager suffix, get prefix, doIt If you wanted to be vague, 
 you should have been a politician 51 @PeterHilton •
  65. 78.

    Use a large vocabulary Use a richer single word instead

    of multiple words that describe a well-known concept. Use the word that most accurately refers to the concept the identifier refers to. ☹ CompanyPerson " Employee, Director, Shareholder Use your thesaurus! 52 @PeterHilton •
  66. 79.

    Use problem domain terms 53 @PeterHilton • Use the correct

    term in the problem domain’s ubiquitous language, and only one term for each concept, within each bounded context. Consistently use the correct domain language terms that subject-matter experts use. ☹ Order instead of Shipment, in supply-chain Warning: you may need to write an actual glossary
  67. 80.

    Omit type information Don’t use prefixes or suffixes that encode

    the data type. Avoid Hungarian notation and its remnants. ☹ isValid, dateCreated, iAppleCount If you didn’t want to name types separately, 
 you should have used JavaScript. 54 @PeterHilton •
  68. 81.

    Prefer collective nouns for collections If a collection’s type has

    a collective noun, in the name’s context, use it instead of a plural. ☹ appointments - replace with " calendar ☹ pickedApples - replace with " harvest Create your own domain-specific collection types 
 instead of always using a List<Something> 55 @PeterHilton •
  69. 82.

    Use opposites precisely Consistently use opposites in standard pairs. Typical

    pairs include: begin/end, create/destroy, destination/source, get/release, increment/decrement, insert/delete, next/previous, old/new, open/close, put/get, show/hide, source/destination, start/stop, target/source ☹ first / end " first / last 56 @PeterHilton •
  70. 83.

    Use a name that allows all possible states Don’t use

    class names that assume a particular state. If a class models something that can have multiple states, then avoid a name that would be inconsistent with the state that results from calling a method that changes that state. ☹ A disable method that returns a ControlEnableState " Rename class to ControlState X @PeterHilton •
  71. 84.

    Choose a name consistent with possible values Don’t use a

    type name that appears to contradict certain possible values. Use a name that applies equally to all values, rather than naming the type after just one possible value ☹ start: LineEnd, end: LineEnd " start: LineExtremity, end: LineExtremity 57 @PeterHilton •
  72. 85.

    Syntax guidelines 1. Use naming conventions 2. Replace numeric suffixes

    3. Use dictionary words 4. Expand single-letter names 5. Articulate symbolic names 6. Name constant values 7. Only use one underscore at a time 8. Only use underscores between words X @PeterHilton •
  73. 86.

    Syntax guidelines 9. Limit name character length 10. Limit name

    word count 11. Qualify values with suffixes 12. Make names unique X @PeterHilton •
  74. 87.

    Vocabulary guidelines 13. Describe meaning 14. Be precise 15. Choose

    concrete words 16. Use standard language 17. Use a large vocabulary 18. Use problem domain terms 19. Make names differ by more than one or two letters 20. Make names differ by more than word order X @PeterHilton •
  75. 88.

    Vocabulary guidelines 21. Make names differ in meaning 22. Make

    names differ phonetically X @PeterHilton •
  76. 89.

    Data type guidelines 23. Omit type information 24. Use singular

    names for values 25. Use plural names for collections 26. Prefer collective nouns for collections 27. Use opposites precisely 28. Use Boolean variable names that imply true or false 29. Use positive Boolean names X @PeterHilton •
  77. 90.

    Class name guidelines 30. Use a noun-phrase name 31. Use

    a name that allows all possible states 32. Choose a name consistent with possible values X @PeterHilton •
  78. 91.

    Method name guidelines X @PeterHilton • 33. Use a verb-phrase

    name 34. Don’t use get, is or has for methods with side-effects 35. Only use get, is and has prefixes for field access 36. Only use get prefix for field accessors that return a value 37. Only use is and has prefixes for Boolean field accessors 38. Only use set for field accessors that don’t return a value 39. Only use validation verbs for methods that return 40. Only use transformation verbs for transformations
  79. 92.

    Naming guidelines for professional programmers, Peter Hilton and Felienne Hermans

    http://hilton.org.uk/presentations/naming-guidelines.html 59 @PeterHilton • Naming guidelines paper
  80. 98.
  81. 99.
  82. 100.

    Programmers Stack Exchange - question by Tragedian answered by gnat

    / CC-BY-SA For naming, there are six techniques that were proven to work for me: 1. spend a lot of time on inventing names 2. use code reviews 3. don’t hesitate to rename 4. spend a lot of time on inventing names 5. use code reviews 6. don’t hesitate to rename
  83. 101.

    Additional benefits If you become a better writer, you could

    use your new skills … for writing X @PeterHilton •
  84. 103.

    ‘A common fallacy is to assume authors of incomprehensible code

    will somehow be able to express themselves lucidly and clearly in comments.’ @KevlinHenney X @PeterHilton •
  85. 104.

    ‘Most of the things programmers say about comments in code

    are excuses for not writing any comments at all.’ @PeterHilton X @PeterHilton •
  86. 105.

    Comments: the basics 1. Don’t say what the code does


    (because the code already says that) 2. Don’t explain awkward logic
 (improve the code to make it clear) 3. Don’t add too many comments
 (it’s messy and they’ll get out of date) X @PeterHilton •
  87. 106.

    Explain why the code exists Even perfect code cannot explain

    its own existence. When should I use this code? When shouldn’t I use it? What are the alternatives to this code? X @PeterHilton •
  88. 107.

    Discover which comments are hard to write, and why If

    a comment is easy to write, then that code doesn’t need a comment. Write a one-sentence comment, for 
 every class and method, to start with. X @PeterHilton •
  89. 108.

    Acknowledge that writing (comments) is a specialist skill On a

    cross-functional development team, not everyone is good at visual design. The same goes for writing about code. Work out who is a better writer. Get help with writing comments. X @PeterHilton •
  90. 109.

    How to write good comments (summary) 1. Try to write

    good code first. 2. Try to write a one-sentence comment. 3. Refactor the code until the comment is easy to write. 4. Now write a good comment. 5. Don’t forget the rules of good writing (e.g. remove unnecessary comments). X @PeterHilton •
  91. 110.
  92. 111.

    Summary 1. Naming is hard 2. Get inspiration from great

    writers 3. Read novels 4. Expand your vocabulary 5. Try actual writing; 
 start with comments, try blogging, 
 but beware of getting sucked into writing a book… 61 @PeterHilton •
  93. 112.

    M A N N I N G Peter Hilton Erik

    Bakker Francisco Canedo FOREWORD BY James Ward Covers Play 2 Play for Scala
 (Manning) 
 Peter Hilton
 Erik Bakker
 Francisco Canedo http://bit.ly/playscala2p
  94. 113.

    There are two problems in computer science. There’s only one

    joke, and it isn’t funny. @PeterHilton • 63
  95. 114.

    @PeterHilton http://hilton.org.uk/ ask about getting a workshop at your company

    Naming is part of Writing maintainable code: Presentation video online (soon) at 
 https://skillsmatter.com/conferences/8784-scala-exchange-2017#skillscasts