Upgrade to Pro — share decks privately, control downloads, hide ads and more …

How to name things: the hardest problem in prog...

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.

Peter Hilton

December 15, 2017
Tweet

More Decks by Peter Hilton

Other Decks in Technology

Transcript

  1. Phil Karlton on naming ‘There are only two hard things

    in Computer Science: cache invalidation and naming things.’ http://hilton.org.uk/blog/why-naming-things-is-hard 2 @PeterHilton •
  2. Person: how does writing work ? Writer: well you type

    & you delete. You rethink. Then you do 187 min of research & correct it. You reread & wonder if you have a grasp of English. Then you revis e Person: then you’re done with the book ? Writer: then you move to the next sentence
  3. Stephen King on pair programming ‘Write with the door closed,

    
 rewrite with the door open.’ 6 @PeterHilton •
  4. Anne Rice on workplace hardware ‘I find the bigger the

    monitor, 
 the better the concentration.’ 8 @PeterHilton •
  5. Ernest Hemingway on user personas ‘When writing a novel a

    writer should create living people; 
 people not characters. 
 A character is a caricature.’ 10 @PeterHilton •
  6. W. Somerset Maugham on enterprise architecture ‘There are three rules

    for writing the novel. Unfortunately, no one knows what they are.’ 12 @PeterHilton •
  7. 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.’ 14 @PeterHilton •
  8. 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.
  9. 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.
  10. 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…
  11. 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.
  12. 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)
  13. ‘What’s in a name? 
 That which we call a

    rose By any other name would smell as sweet’ Romeo and Juliet, 
 W. Shakespeare Cristian Newman
  14. Deliberately meaningless names In theory, foo is only used as

    a placeholder name* 
 (because it doesn’t mean anything) * a.k.a. metasyntactic variable https://en.wikipedia.org/wiki/Metasyntactic_variable 25 @PeterHilton •
  15. ‘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.’ ‘A rose by any other name will end up as a cabbage’ 
 by Sam Gardiner 97 Things Every Software Architect Should Know mattia barbotti
  16. What is the worst ever variable name? data What is

    the second-worst name? data2 What is the third-worst name ever? data_2 28 @PeterHilton •
  17. Abbreviations are ambiguous Is char a character or characteristic? Does

    mod mean modify or modulo? What about acc, pos or auth? People only use auth because they can’t remember the difference between authentication and authorisation 29 @PeterHilton •
  18. Redundant words dilute meaning invoice invoice_document order_invoice_document_file ‘This is like

    homeopathy. What you’ve done is you’ve diluted the meaning until it’s all gone.’ @KevlinHenney 30 @PeterHilton •
  19. CRUD are not the only verbs SQL simplifies English to

    four verbs (CRUD🤦): insert, select, update, delete This isn’t appropriate in other contexts, e.g. event naming in message-based architectures: address_updated → customer_moved_house 31 @PeterHilton •
  20. ‘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, Lewis Carroll
  21. Wrong words are wrong, synonyms are confusing order ≠ shipment

    carrier ≠ broker shipment ≠ transport leg shipment = consignment carrier = transporter transport leg = journey 33 @PeterHilton •
  22. Summary of naming things badly Meaningless: foo Vague: data Verbose:

    text_correction_by_editor Abbreviated: acc Diluted: order_invoice_document_file CRUDdy: address_updated Wrong: shipment 34 @PeterHilton •
  23. 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. 36 @PeterHilton •
  24. Improve your vocabulary Read books, preferably ones you enjoy 😀

    Play word games with someone who always wins. 
 Until they don’t. 37 @PeterHilton •
  25. I had an argument with a 
 coworker about what

    
 variable names we 
 should use in 
 for loops i won 
 
 Lou Creemers @lovelacecoding Olga Nayda
  26. 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. 42 @PeterHilton •
  27. Learn domain-specific vocabulary Scan the domain model entities’ Wikipedia pages

    for names of related concepts. Read novels and watch films set in your customer’s domain, to learn their jargon. 43 @PeterHilton •
  28. 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
  29. The Gaiman principle: if someone tells you that one name

    is better than another for them, then believe them @PeterHilton • 45
  30. Overcome fear of renaming The only thing harder than naming

    is renaming. Renaming requires naming… 
 plus change, a conversation, and new understanding. Rename is the safest but most effective refactoring. Use it. 46 @PeterHilton •
  31. Adopt better naming practices 1. Use words with precise meanings

    2. Adopt naming guidelines 3. Use code review pair programming to improve names 4. Read code out loud to check that it sounds okay 5. Don’t expect to get the perfect name at first 6. Actually rename things 47 @PeterHilton •
  32. 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 49 @PeterHilton •
  33. 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) 50 @PeterHilton •
  34. Limit name word count Keep name length within a four

    word maximum, and 
 avoid gratuitous context, e.g. the same prefix for all names. 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) 51 @PeterHilton •
  35. 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 or a_date, etc. ☹ foo, blah, flag, temp In code review, ask, ‘What is a Foo?’ 52 @PeterHilton •
  36. 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! 53 @PeterHilton •
  37. Use problem domain terms 54 @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
  38. 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 You can’t do this with relational database table names, because they’re supposed to be singular 😬 55 @PeterHilton •
  39. Use opposites precisely Consistently use opposites in standard pairs. Typical

    pairs include: create/destroy, insert/delete, destination/source, get/release, increment/decrement, next/previous, old/new, open/close, fetch/send, show/hide, source/destination, start/stop, target/source, begin/end ☹ first / end 😀 first / last 56 @PeterHilton •
  40. Naming guidelines 57 @PeterHilton • 1. Use established 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
  41. Naming guidelines for professional programmers, Peter Hilton and Felienne Hermans

    http://hilton.org.uk/presentations/naming-guidelines.html 58 @PeterHilton • Naming guidelines
  42. Summary 1. Naming is hard 2. Get inspiration from great

    writers - read their novels 3. Expand your vocabulary 4. Identify (and name!) anti-patterns and guidelines 5. Try actual writing; 
 start with comments, try blogging, 
 but beware of getting sucked into writing a book… 60 @PeterHilton •
  43. M A N N I N G Peter Hilton Erik

    Bakker Francisco Canedo FOREWORD BY James Ward Covers Play 2 Play for Scala 
 (Manning, 2013) 
 Peter Hilton 
 Erik Bakker 
 Francisco Canedo http://bit.ly/playscala2p
  44. @PeterHilton http://hilton.org.uk/ Writing maintainable code Naming is part of the

    one-day training course: https://hilton.org.uk/training/maintainable-code