Name in Vain: Improving design one word at a time
- 1. linkedin/borislit github.com/borislit@borislitborisl@wix.com Name in Vain Improving design one word at a time
- 2. Hi. I am Boris Litvinsky Frontend Developer @ WIX Bookings Lithuania Ukraine Vilnius Kiev Dnipro Wix Engineering Locations Israel Tel-Aviv Be’er Sheva
- 4. Readable by Computer is Easy
- 5. Readable by Humans is Difficult
- 6. It’s much more like studying 17th century French poetry - WTF did this guy mean? “ “ “ David Heinemeier Hansson
- 7. You can name your kid anything you want. There are no laws. There should be couple of laws - Louis CK “ “
- 9. Naming Matters ▪ Discussing Names = Discussing the Product ▪ May signify a problem in a design ▪ Shortens the learning curve ▪ “The Six Month Rule” http://blog.marcomonteiro.net/post/the-six-months-rule
- 10. The reason that they think the old code is a mess is because of a fundamental law of programming: It’s harder to read code than to write it. “ “ “ David Heinemeier HanssonJoel Spolsky
- 12. Vague, Meaningless Names ▪ Your “Managers”, Your “Services”, Your “Handler” ▪ Your “object”, Your “data” Don't express their role in the system Eventually become a bag of methods Usually cause SRP violation = Increase size & coupling Don't express their role in the system Eventually become a bag of methods
- 13. Abbreviations are Ambitious ▪ char - is it a “character” or “characteristic” ? ▪ mod - is it “modify” or “modulo”? Compels you to read the code You can’t use them in a conversation Compels you to read the code
- 14. Too Many Words ▪ dontTryToWriteWholeSentencesWithYourDamnFunctionName ▪ How is “company_person” better than “employee” ? http://wiki.c2.com/?MeaningfulName http://hilton.org.uk/blog/naming-smells Difficult to remember Difficult to spot differences Difficult to remember oneHorribleDescriptiveLongNameVersion vs oneHorribleDestructiveLongSameVersion You probably don’t know what it is You probably don’t know what it is
- 15. × ✓car.startEngine() car.start() Excess Nouns in Function Names Nouns are implementation details, that the caller knows about ▪ Perfectly fine if the noun is one of the parameters, e.g., car.startPowerProvider(powerProvider) ▪ Getters are horrible
- 16. Too Much Context × ✓ class PendingPaymentRecord() {} class PaymentRecord() {} Prevents reuse of objects/meth ods in other valid cases
- 17. We Resolve to Basic Instincts
- 18. Lack of Domain Knowledge Domain - A subject the software is being developed for.
- 19. But... ▪ How can you build software without understanding the problem it’s solving? ▪ How can you apply new requirements to software that doesn't reflect the domain? ▪ How can you name something you don’t understand?
- 21. Consumer Vocabulary Domain Model A simplified representation of domain knowledge. * Created by software expert & domain expert Defines a Ubiquitous Language - vocabulary used by everybody, everywhere
- 22. Names should reference the Ubiquitous Language
- 24. Clean code reads like well-written prose “ “ “ David Heinemeier HanssonRobert C. Martin
- 25. Well Written Prose “Prose is a form of language that exhibits a grammatical structure and a natural flow of speech” - Wikipedia https://en.wikipedia.org/wiki/Prose https://www.citerus.se/specification-pattern-as-a-re factoring-tool //Example 1 if(car.speed() > 2 * SPEED_LIMIT) { speaker.generateAlert('Police reported ahead'); } //Example 2 const candidateCarSpecification = colorRed .and(inApprovedCity.or(convertible)); if (candidateCarSpecification.isSatisfiedBy(car)) { //... }
- 26. Classes Nouns ● Should describe the role it fulfils in the system ● Should allow the class to be easily located and evaluated
- 27. Methods ▪ Help us identify additional responsibilities, e.g., DoesThisAndThat() https://www.youtube.com/watch?v=4cVZvoFGJTU&t=239s RuleEvaluator +evaluate(string) -parseAdjunctTerm() -parseFactorTerm() -parseAdjunct() -hasMoreTokens() -getNextToken() RuleEvaluator +evaluate(string) -parseAdjunctTerm() -parseFactorTerm() -parseAdjunct() RuleTokenizer +hasMoreTokens() +getNextToken()
- 28. Methods ▪ Help us identify additional responsibilities ▪ Those without side-effects should read as noun e.g player.balance() ▪ Those with side-effects should read as verbs e.g player.start() ▪ Can include prepositions (Of, To, For) to help describe relationships to parameters e.g payAmountOf(...) or moveTo(...) ▪ Describe everything it does - no surprises!
- 29. Interfaces Adjectives ▪ There’s no “I” in Interface ▪ Describes a capability ▪ Deliverable, Shippable, Printable
- 30. Booleans Auxiliary / Helping Verbs ▪ is, should, can, has ▪ if( piece.isOn(square) ) {...} if( player.hasBalanceOf(amount) ) {...} if( player.canPurchase(property) ) {...}
- 31. 6 Things to Remember ★ Renaming is part of refactoring! ★ Use the consumer’s vocabulary ★ Make sure you can read what you write ★ Be open for feedback ★ Communicate names/renames to other people. Be consistent Don’t give up! Struggle for every word.