Tweet
Tweet

Slide 1

Slide 1 text

@PeterHilton http://hilton.org.uk/ How to name things: the hardest problem in ✨data modelling✨

Slide 2

Slide 2 text

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 •

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

Advice from writers

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

Stephen King on pair programming ‘Write with the door closed, 
 rewrite with the door open.’ 6 @PeterHilton •

Slide 7

Slide 7 text

warriorwoman531 / CC BY-ND 2.0

Slide 8

Slide 8 text

Anne Rice on workplace hardware ‘I find the bigger the monitor, 
 the better the concentration.’ 8 @PeterHilton •

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

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 •

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

W. Somerset Maugham on enterprise architecture ‘There are three rules for writing the novel. Unfortunately, no one knows what they are.’ 12 @PeterHilton •

Slide 13

Slide 13 text

ranh / CC BY 2.0

Slide 14

Slide 14 text

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 •

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

George Orwell’s rules for naming

Slide 18

Slide 18 text

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.

Slide 19

Slide 19 text

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.

Slide 20

Slide 20 text

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…

Slide 21

Slide 21 text

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.

Slide 22

Slide 22 text

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)

Slide 23

Slide 23 text

Naming things badly

Slide 24

Slide 24 text

‘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

Slide 25

Slide 25 text

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 •

Slide 26

Slide 26 text

⬇︎ 185 million

Slide 27

Slide 27 text

‘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

Slide 28

Slide 28 text

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 •

Slide 29

Slide 29 text

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 •

Slide 30

Slide 30 text

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 •

Slide 31

Slide 31 text

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 •

Slide 32

Slide 32 text

‘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

Slide 33

Slide 33 text

Wrong words are wrong, synonyms are confusing order ≠ shipment carrier ≠ broker shipment ≠ transport leg shipment = consignment carrier = transporter transport leg = journey 33 @PeterHilton •

Slide 34

Slide 34 text

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 •

Slide 35

Slide 35 text

Getting better at naming

Slide 36

Slide 36 text

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 •

Slide 37

Slide 37 text

Improve your vocabulary Read books, preferably ones you enjoy 😀 Play word games with someone who always wins. 
 Until they don’t. 37 @PeterHilton •

Slide 38

Slide 38 text

Piotr / CC BY 2.0

Slide 39

Slide 39 text

Janko Ferlič

Slide 40

Slide 40 text

Improve your general vocabulary Use your dictionary and thesaurus… 40 @PeterHilton •

Slide 41

Slide 41 text

I had an argument with a 
 coworker about what 
 variable names we 
 should use in 
 for loops i won 
 
 Lou Creemers @lovelacecoding Olga Nayda

Slide 42

Slide 42 text

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 •

Slide 43

Slide 43 text

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 •

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

The Gaiman principle: if someone tells you that one name is better than another for them, then believe them @PeterHilton • 45

Slide 46

Slide 46 text

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 •

Slide 47

Slide 47 text

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 •

Slide 48

Slide 48 text

Naming guidelines

Slide 49

Slide 49 text

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 •

Slide 50

Slide 50 text

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 •

Slide 51

Slide 51 text

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 •

Slide 52

Slide 52 text

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 •

Slide 53

Slide 53 text

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 •

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

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 •

Slide 56

Slide 56 text

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 •

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

Naming guidelines for professional programmers, Peter Hilton and Felienne Hermans http://hilton.org.uk/presentations/naming-guidelines.html 58 @PeterHilton • Naming guidelines

Slide 59

Slide 59 text

Summary

Slide 60

Slide 60 text

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 •

Slide 61

Slide 61 text

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

Slide 62

Slide 62 text

@PeterHilton http://hilton.org.uk/ Writing maintainable code Naming is part of the one-day training course: https://hilton.org.uk/training/maintainable-code