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.

Transcript

1. @PeterHilton http://hilton.org.uk/ How to name things: the hardest problem in ✨data modelling✨
2. 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 •
3. 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
4. Advice from writers
6. Stephen King on pair programming ‘Write with the door closed, 
 rewrite with the door open.’ 6 @PeterHilton •
7. warriorwoman531 / CC BY-ND 2.0
8. Anne Rice on workplace hardware ‘I find the bigger the monitor, 
 the better the concentration.’ 8 @PeterHilton •
10. 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 •
12. W. Somerset Maugham on enterprise architecture ‘There are three rules for writing the novel. Unfortunately, no one knows what they are.’ 12 @PeterHilton •
13. ranh / CC BY 2.0
14. 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 •
17. George Orwell’s rules for naming
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.
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.
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…
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.
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)
23. Naming things badly
24. ‘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
25. 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 •
26. ⬇︎ 185 million
27. ‘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
28. 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 •
29. 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 •
30. 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 •
31. 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 •
32. ‘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
33. Wrong words are wrong, synonyms are confusing order ≠ shipment carrier ≠ broker shipment ≠ transport leg shipment = consignment carrier = transporter transport leg = journey 33 @PeterHilton •
34. 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 •
35. Getting better at naming
36. 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 •
37. Improve your vocabulary Read books, preferably ones you enjoy 😀 Play word games with someone who always wins. 
 Until they don’t. 37 @PeterHilton •
38. Piotr / CC BY 2.0
39. Janko Ferlič
40. Improve your general vocabulary Use your dictionary and thesaurus… 40 @PeterHilton •
41. I had an argument with a 
 coworker about what 
 variable names we 
 should use in 
 for loops i won 
 
 Lou Creemers @lovelacecoding Olga Nayda
42. 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 •
43. 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 •
44. 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
45. The Gaiman principle: if someone tells you that one name is better than another for them, then believe them @PeterHilton • 45
46. 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 •
47. 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 •
48. Naming guidelines
49. 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 •
50. 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 •
51. 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 •
52. 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 •
53. 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 •
54. 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
55. 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 •
56. 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 •
57. 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
58. Naming guidelines for professional programmers, Peter Hilton and Felienne Hermans http://hilton.org.uk/presentations/naming-guidelines.html 58 @PeterHilton • Naming guidelines
59. Summary
60. 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 •
61. 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
62. @PeterHilton http://hilton.org.uk/ Writing maintainable code Naming is part of the one-day training course: https://hilton.org.uk/training/maintainable-code