Naming Things - Speaker Deck

Naming Things

by Dane Šoba

Slide 1

Slide 1 text

NAMING THINGS DANE ŠOBA [email protected]

Slide 2

Slide 2 text

THERE ARE ONLY TWO HARD THINGS IN COMPUTER SCIENCE: CACHE INVALIDATION AND NAMING THINGS. Phil Karlton NAMING THINGS

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

NAMING THINGS THINK FIRST ▸ Understand the problem first ▸ Clear purpose = clear name ▸ word definitions, wikipedia, synonyms ▸ Google: define [word]

Slide 5

Slide 5 text

NAMING THINGS AVOID TEMPORARY NAMES ▸ x, i, j, n, foo, bar, tmp ▸ conveys no information ▸ every variable is temporary

Slide 6

Slide 6 text

NAMING THINGS AVOID TEMPORARY NAMES ▸ use speciﬁc names: user, index, swap tmp = a a = b b = tmp swap = a a = b b = swap

Slide 7

Slide 7 text

NAMING THINGS AVOID TEMPORARY NAMES ▸ use language constructs instead tmp = a a = b b = tmp a,b = b,a

Slide 8

Slide 8 text

NAMING THINGS AVOID TEMPORARY NAMES ▸ name indexes for(i=0; i=i; j--) for (leftIndex=0; leftIndex= leftIndex; rightIndex-- ) ▸ or use functional programming (map, ﬁlter, reduce, …)

Slide 9

Slide 9 text

NAMING THINGS GIVE NAMES TO THINGS ▸ DRY ▸ extract expressions ▸ refactor code ▸ local variables are cheap, programmers aren’t ▸ readability and maintainability

Slide 10

Slide 10 text

NAMING THINGS GIVE NAMES TO THINGS # check if user can edit order if user.merchant? && order.provider === user && order.editable?

Slide 11

Slide 11 text

NAMING THINGS GIVE NAMES TO THINGS user_can_edit_order = user.merchant? && order.provider === user && order.editable? if user_can_edit_order ▸ extract expression

Slide 12

Slide 12 text

NAMING THINGS GIVE NAMES TO THINGS if user.can_edit_order? order ▸ refactor to method

Slide 13

Slide 13 text

NAMING THINGS DON’T BE SURPRISING ▸ Don’t mislead ▸ Principle of least surprise ▸ Important for APIs

Slide 14

Slide 14 text

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() );

Slide 15

Slide 15 text

NAMING THINGS DON’T BE SURPRISING New year started on 5. 0. in the year 116

Slide 16

Slide 16 text

NAMING THINGS DON’T BE SURPRISING ▸ Why? getDay() getMonth() getYear() day of week (sunday is 0) month of year (0-based) years since 1900

Slide 17

Slide 17 text

NAMING THINGS DON’T BE SURPRISING ▸ The “right” way getDay() getMonth() getYear() getDate() getMonth() + 1 getFullYear()

Slide 18

Slide 18 text

NAMING THINGS CHECK SPELLING ▸ Always check spelling ▸ Mistakes are harder to ﬁx later

Slide 19

Slide 19 text

NAMING THINGS CHECK SPELLING ▸ referer / referrer ▸ HTTP spec got it wrong

Slide 20

Slide 20 text

NAMING THINGS NAME EQUAL THINGS EQUALLY ▸ Be consistent with naming ▸ Reuse the same names for same concepts

Slide 21

Slide 21 text

NAMING THINGS NAME DIFFERENT THINGS DIFFERENTLY ▸ Use different names for different concepts ▸ Use synonyms to ﬁnd different words ▸ Google: [word] synonyms

Slide 22

Slide 22 text

NAMING THINGS NAME DIFFERENT THINGS DIFFERENTLY kind mark graphic type tag image WORD SYNONYM

Slide 23

Slide 23 text

NAMING THINGS AVOID AMBIGUITY ▸ a word can have different meanings ▸ avoid words with misleading meanings ▸ use synonyms to ﬁnd better words

Slide 24

Slide 24 text

NAMING THINGS AVOID AMBIGUITY parking.free? ▸ is the parking free of charge or available?

Slide 25

Slide 25 text

NAMING THINGS AVOID AMBIGUITY parking.free? parking.gratis? parking.available?

Slide 26

Slide 26 text

NAMING THINGS RENAME THINGS ▸ Rename things when meanings change ▸ Improves understanding ▸ Avoids confusion

Slide 27

Slide 27 text

NAMING THINGS RENAME THINGS @enable_sorting ▸ enabled drag-drop reordering on table (jquery sortable) ▸ new requirement: allow sorting by table column

Slide 28

Slide 28 text

NAMING THINGS RENAME THINGS @enable_sorting @enable_reordering @enable_sorting ▸ drag-drop reordering ▸ sort by column

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

NAMING THINGS AVOID ENTERPRISEY NAMES AbstractSingletonProxyFactoryBean “Convenient proxy factory bean superclass for proxy factory beans that create only singletons.”

Slide 31

Slide 31 text

NAMING THINGS AVOID SMURF NAMING SmurfModule::SmurfClass.apply_smurf_method

Slide 32

Slide 32 text

NAMING THINGS MAKE NAMES SEARCHABLE ▸ Allow searching the project for speciﬁc code ▸ Important in dynamic languages

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

NAMING THINGS DON’T ABBREVIATE ▸ Harder to read ▸ Harder to understand ▸ Harder to search ▸ Write for humans

Slide 35

Slide 35 text

NAMING THINGS DON’T ABBREVIATE usr_sel_crncy

Slide 36

Slide 36 text

NAMING THINGS DON’T ABBREVIATE user_selected_currency

Slide 37

Slide 37 text

NAMING THINGS DON’T BE TOO GENERIC ▸ Avoid generic words ▸ entity, object ▸ No added information ▸ Harder to understand intent

Slide 38

Slide 38 text

NAMING THINGS DON'T BE TOO GENERIC labrador dog animal being entity Speciﬁc Generic

Slide 39

Slide 39 text

NAMING THINGS BE CONCISE ▸ Don’t be too speciﬁc ▸ Requirements change ▸ Not enough added info beyond a point

Slide 40

Slide 40 text

NAMING THINGS BE CONCISE XmlThirdPartyExport ▸ Export data for 3rd party partners via XML feeds ▸ New requirements ▸ XML -> JSON, CSV, TSV ▸ 3rd Party -> used internally

Slide 41

Slide 41 text

NAMING THINGS BE CONCISE XmlThirdPartyExport DataExport

Slide 42

Slide 42 text

NAMING THINGS ADD CONTEXT ▸ Expand short names with extra info ▸ Clarify intent ▸ Avoid confusion

Slide 43

Slide 43 text

NAMING THINGS ADD CONTEXT discount

Slide 44

Slide 44 text

NAMING THINGS ADD CONTEXT discount ▸ Percent? (-50%) ▸ Amount? (-10 EUR)

Slide 45

Slide 45 text

NAMING THINGS ADD CONTEXT discount discount_percent discount_amount

Slide 46

Slide 46 text

NAMING THINGS ADD CONTEXT ▸ Duplicating an offer offer = Offer.find(params[:id]) offer2 = offer.dup

Slide 47

Slide 47 text

NAMING THINGS ADD CONTEXT ▸ Duplicating an offer old_offer = Offer.find(params[:id]) new_offer = old_offer.dup

Slide 48

Slide 48 text

NAMING THINGS USE THE PROJECT’S NAMING CONVENTIONS ▸ especially if you don’t agree with them ▸ consistency > preference ▸ write for your team

Slide 49

Slide 49 text

NAMING THINGS NAME PROJECTS EARLY ▸ discussions & meetings ▸ packages ▸ classes ▸ namespaces ▸ identiﬁers ▸ api keys ▸ conﬁg ▸ web domains ▸ technical references ▸ social media Project name used in:

Slide 50

Slide 50 text

NAMING THINGS NAME PROJECTS EARLY ▸ temporary javax namespace ▸ couldn’t change to java.swing ▸ books & references already printed javax.swing

Slide 51

Slide 51 text

WHAT’S IN A NAME? A ROSE BY ANY OTHER NAME WOULD SMELL AS SWEET William Shakespeare NAMING THINGS