Naming Things

A talk about naming in code.

https://www.youtube.com/watch?v=aXPZD1IxanY

Presented at Ruby Meetup Ljubljana on 26. May 2016

Transcript

1. NAMING THINGS DANE ŠOBA DANE.SOBA@GMAIL.COM
2. THERE ARE ONLY TWO HARD THINGS IN COMPUTER SCIENCE: CACHE INVALIDATION AND NAMING THINGS. Phil Karlton NAMING THINGS
3. NAMING THINGS WHY IS NAMING IN CODE IMPORTANT? ▸ code is read more than written ▸ naming = understanding ▸ readability = maintainability ▸ discoverability of APIs ▸ write for people, not machines
4. NAMING THINGS THINK FIRST ▸ Understand the problem first ▸ Clear purpose = clear name ▸ word definitions, wikipedia, synonyms ▸ Google: define [word]
5. NAMING THINGS AVOID TEMPORARY NAMES ▸ x, i, j, n, foo, bar, tmp ▸ conveys no information ▸ every variable is temporary
6. NAMING THINGS AVOID TEMPORARY NAMES ▸ use specific names: user, index, swap tmp = a a = b b = tmp swap = a a = b b = swap
7. NAMING THINGS AVOID TEMPORARY NAMES ▸ use language constructs instead tmp = a a = b b = tmp a,b = b,a
8. NAMING THINGS AVOID TEMPORARY NAMES ▸ name indexes for(i=0; i<items.length-1; i++) for(j=items.length-1; j>=i; j--) for (leftIndex=0; leftIndex<items.length-1; leftIndex++) for (rightIndex = items.length-1; rightIndex >= leftIndex; rightIndex-- ) ▸ or use functional programming (map, filter, reduce, …)
9. NAMING THINGS GIVE NAMES TO THINGS ▸ DRY ▸ extract expressions ▸ refactor code ▸ local variables are cheap, programmers aren’t ▸ readability and maintainability
10. NAMING THINGS GIVE NAMES TO THINGS # check if user can edit order if user.merchant? && order.provider === user && order.editable?
11. NAMING THINGS GIVE NAMES TO THINGS user_can_edit_order = user.merchant? && order.provider === user && order.editable? if user_can_edit_order ▸ extract expression
12. NAMING THINGS GIVE NAMES TO THINGS if user.can_edit_order? order ▸ refactor to method
13. NAMING THINGS DON’T BE SURPRISING ▸ Don’t mislead ▸ Principle of least surprise ▸ Important for APIs
14. NAMING THINGS DON’T BE SURPRISING ▸ What does this code output? date = new Date('2016-01-01'); console.log("New year started on"+ date.getDay()+". "+ date.getMonth()+". in the year"+ date.getYear() );
15. NAMING THINGS DON’T BE SURPRISING New year started on 5. 0. in the year 116
16. NAMING THINGS DON’T BE SURPRISING ▸ Why? getDay() getMonth() getYear() day of week (sunday is 0) month of year (0-based) years since 1900
17. NAMING THINGS DON’T BE SURPRISING ▸ The “right” way getDay() getMonth() getYear() getDate() getMonth() + 1 getFullYear()
18. NAMING THINGS CHECK SPELLING ▸ Always check spelling ▸ Mistakes are harder to fix later
19. NAMING THINGS CHECK SPELLING ▸ referer / referrer ▸ HTTP spec got it wrong
20. NAMING THINGS NAME EQUAL THINGS EQUALLY ▸ Be consistent with naming ▸ Reuse the same names for same concepts
21. NAMING THINGS NAME DIFFERENT THINGS DIFFERENTLY ▸ Use different names for different concepts ▸ Use synonyms to find different words ▸ Google: [word] synonyms
22. NAMING THINGS NAME DIFFERENT THINGS DIFFERENTLY kind mark graphic type tag image WORD SYNONYM
23. NAMING THINGS AVOID AMBIGUITY ▸ a word can have different meanings ▸ avoid words with misleading meanings ▸ use synonyms to find better words
24. NAMING THINGS AVOID AMBIGUITY parking.free? ▸ is the parking free of charge or available?
25. NAMING THINGS AVOID AMBIGUITY parking.free? parking.gratis? parking.available?
26. NAMING THINGS RENAME THINGS ▸ Rename things when meanings change ▸ Improves understanding ▸ Avoids confusion
27. NAMING THINGS RENAME THINGS @enable_sorting ▸ enabled drag-drop reordering on table (jquery sortable) ▸ new requirement: allow sorting by table column
28. NAMING THINGS RENAME THINGS @enable_sorting @enable_reordering @enable_sorting ▸ drag-drop reordering ▸ sort by column
29. NAMING THINGS OPPOSITE NAME PAIRS ▸ Use appropriate name pairs for opposites get/set login/logout read/write get/change login/signout input/write GOOD BAD ▸ Google: [word] antonym
30. NAMING THINGS AVOID ENTERPRISEY NAMES AbstractSingletonProxyFactoryBean “Convenient proxy factory bean superclass for proxy factory beans that create only singletons.”
31. NAMING THINGS AVOID SMURF NAMING SmurfModule::SmurfClass.apply_smurf_method
32. NAMING THINGS MAKE NAMES SEARCHABLE ▸ Allow searching the project for specific code ▸ Important in dynamic languages
33. NAMING THINGS MAKE NAMES SEARCHABLE ▸ Enables A/B experiment in different parts of the app ▸ Find all related code with 1 search @ab_improved_checkout
34. NAMING THINGS DON’T ABBREVIATE ▸ Harder to read ▸ Harder to understand ▸ Harder to search ▸ Write for humans
35. NAMING THINGS DON’T ABBREVIATE usr_sel_crncy
36. NAMING THINGS DON’T ABBREVIATE user_selected_currency
37. NAMING THINGS DON’T BE TOO GENERIC ▸ Avoid generic words ▸ entity, object ▸ No added information ▸ Harder to understand intent
38. NAMING THINGS DON'T BE TOO GENERIC labrador dog animal being entity Specific Generic
39. NAMING THINGS BE CONCISE ▸ Don’t be too specific ▸ Requirements change ▸ Not enough added info beyond a point
40. NAMING THINGS BE CONCISE XmlThirdPartyExport ▸ Export data for 3rd party partners via XML feeds ▸ New requirements ▸ XML -> JSON, CSV, TSV ▸ 3rd Party -> used internally
41. NAMING THINGS BE CONCISE XmlThirdPartyExport DataExport
42. NAMING THINGS ADD CONTEXT ▸ Expand short names with extra info ▸ Clarify intent ▸ Avoid confusion
43. NAMING THINGS ADD CONTEXT discount
44. NAMING THINGS ADD CONTEXT discount ▸ Percent? (-50%) ▸ Amount? (-10 EUR)
45. NAMING THINGS ADD CONTEXT discount discount_percent discount_amount
46. NAMING THINGS ADD CONTEXT ▸ Duplicating an offer offer = Offer.find(params[:id]) offer2 = offer.dup
47. NAMING THINGS ADD CONTEXT ▸ Duplicating an offer old_offer = Offer.find(params[:id]) new_offer = old_offer.dup
48. NAMING THINGS USE THE PROJECT’S NAMING CONVENTIONS ▸ especially if you don’t agree with them ▸ consistency > preference ▸ write for your team
49. NAMING THINGS NAME PROJECTS EARLY ▸ discussions & meetings ▸ packages ▸ classes ▸ namespaces ▸ identifiers ▸ api keys ▸ config ▸ web domains ▸ technical references ▸ social media Project name used in:
50. NAMING THINGS NAME PROJECTS EARLY ▸ temporary javax namespace ▸ couldn’t change to java.swing ▸ books & references already printed javax.swing
51. WHAT’S IN A NAME? A ROSE BY ANY OTHER NAME WOULD SMELL AS SWEET William Shakespeare NAMING THINGS
52. WHAT’S IN A NAME? CODE BY ANY OTHER NAME WOULD SMELL Dane Šoba NAMING THINGS
53. QUESTIONS?