Naming Things

I gave this talk at the PHPUK15 in London

Transcript

1. NAMING THINGS
   THE ART OF WRITING MEANINGFUL CODE
   FEBRUARY 2015
   PHPUK15
   

   View Slide

2. ANNE-JULIA SCHEUERMANN
   on twitter
   on github.com
   Naming things (mostly PHP) for over ten years now
   Seen all of what I will show you in a few minutes
   Tech Lead at Imagine Easy Solutions
   @dazzlog
   @dazz
   

   View Slide

3. We create solutions for teachers and
   students to promote writing, research and
   critical thinking skills, which are instrumental
   for success in school and career.
   

   View Slide

4. WHY ARE WE
   NAMING THINGS ?
   

   View Slide

5. ASSEMBLY
   

   View Slide

6. ROCK ART
   

   View Slide

7. CONTEXT
   

   View Slide

8. THING
   +
   CONTEXT
   =
   MEANING
   

   View Slide

9. GENERAL ADVICES
   

   View Slide

10. AVD. ABBRVTN.
    BAD:
    S
    r
    v
    M
    g
    r
    I
    n
    s
    t
    a
    n
    c
    e
    D
    e
    s
    c
    r
    i
    p
    t
    o
    r
    F
    a
    c
    t
    o
    r
    y
    $
    c
    t
    r
    l
    , $
    c
    t
    r
    $
    t
    m
    p
    l
    $
    l
    i
    s
    t
    -
    >
    s
    r
    t
    (
    )
    ;
    GOOD:
    I
    m
    p
    l
    e
    m
    e
    n
    t
    a
    t
    i
    o
    n
    $
    c
    o
    n
    t
    r
    o
    l
    l
    e
    r
    $
    t
    e
    m
    p
    l
    a
    t
    e
    $
    l
    i
    s
    t
    -
    >
    s
    o
    r
    t
    (
    )
    

    View Slide

11. ACRONYMS IN UPPERCASE
    OK:
    P
    d
    f
    U
    r
    l
    U
    u
    i
    d
    BETTER:
    P
    D
    F
    U
    R
    L
    U
    U
    I
    D
    

    View Slide

12. CODE IN ENGLISH
    BAD:
    $
    o
    b
    j
    e
    c
    t
    -
    >
    v
    i
    s
    i
    b
    l
    e
    E
    h
    (
    )
    ;
    $
    h
    r = $
    v
    e
    r
    b
    a
    l
    e
    -
    >
    o
    p
    e
    n
    B
    y
    I
    D
    (
    $
    i
    d
    V
    e
    r
    b
    a
    l
    e
    )
    ;
    GOOD:
    O
    n
    l
    y (
    a
    m
    e
    r
    i
    c
    a
    n
    ) e
    n
    g
    l
    i
    s
    h w
    i
    t
    h
    o
    u
    t e
    x
    c
    e
    p
    t
    i
    o
    n
    s
    !
    

    View Slide

13. DON'T USE UNICODE
    BAD:
    क = 1
    ; कु
    ल = 0
    ;
    जब तक क छोटा है
    1
    0 से {
    कु
    ल +
    = क;
    }
    ALSO BAD:
    p
    u
    b
    l
    i
    c e
    n
    u
    m Т
    о
    в
    а
    р
    ы
    {
    Т
    е
    т
    р
    а
    д
    и = 2
    ,
    К
    а
    р
    а
    н
    д
    а
    ш
    и = 4
    ,
    В
    с
    ё = Т
    е
    т
    р
    а
    д
    и | К
    а
    р
    а
    н
    д
    а
    ш
    и
    }
    

    View Slide

14. REALLY, NO UNICODE!
    FUNNY, EH?
    

    View Slide

15. 1337 SP34K
    IS NOT COOL
    BAD:
    L
    3
    3
    t
    C
    o
    n
    t
    r
    o
    1
    1
    3
    r
    $
    o
    b
    j
    -
    >
    k
    1
    l
    l
    4
    l
    l
    3
    n
    3
    m
    i
    3
    s
    (
    )
    ;
    $
    n
    u
    m
    b
    3
    r
    GOOD:
    O
    n
    l
    y e
    n
    g
    l
    i
    s
    h w
    i
    t
    h
    o
    u
    t e
    x
    c
    e
    p
    t
    i
    o
    n
    s
    !
    

    View Slide

16. DON'T SWEAR
    BAD:
    $
    c
    o
    n
    t
    r
    o
    l
    l
    e
    r
    -
    >
    h
    e
    l
    l
    N
    o
    (
    )
    ;
    $
    f
    u
    k
    c
    Y
    o
    u
    I
    d
    ;
    GOOD:
    /
    / n
    o
    t e
    v
    e
    n i
    n y
    o
    u
    r *
    *
    * c
    o
    m
    m
    e
    n
    t
    s
    

    View Slide

17. DELETE LEGACY CODE
    BAD:
    N
    e
    w
    H
    a
    n
    d
    l
    e
    r
    $
    o
    b
    j
    -
    >
    b
    u
    i
    l
    d
    C
    o
    n
    t
    e
    x
    t
    F
    a
    s
    t
    e
    r
    (
    )
    ;
    GOOD:
    delete old code! you have a version control system
    

    View Slide

18. USER STORY FIRST
    “As a student, I want to view all my
    assignments on an overview page.”
    OK:
    A
    s
    s
    i
    g
    n
    m
    e
    n
    t
    L
    i
    s
    t
    GOOD:
    A
    s
    s
    i
    g
    n
    m
    e
    n
    t
    O
    v
    e
    r
    v
    i
    e
    w
    

    View Slide

19. VARIABLES
    

    View Slide

20. AVOID SINGLE CHARACTER
    VARIABLES
    BAD:
    $
    a
    , $
    b
    , $
    c
    ;
    $
    w
    -
    >
    t
    (
    $
    f
    )
    ;
    OK:
    $
    i /
    / i
    n f
    o
    r
    -
    l
    o
    o
    p
    s
    $
    x
    , $
    y
    , $
    z /
    / c
    o
    o
    r
    d
    i
    n
    a
    t
    e
    s
    

    View Slide

21. DON'T INCREMENT
    BAD:
    $
    t
    a
    b
    l
    e
    1
    , $
    t
    a
    b
    l
    e
    2
    , .
    .
    .
    $
    k
    e
    e
    p
    A
    , $
    k
    e
    e
    p
    B
    GOOD:
    $
    t
    a
    b
    l
    e
    , $
    t
    a
    b
    l
    e
    T
    o
    C
    o
    m
    p
    a
    r
    e
    T
    o
    $
    i
    n
    t
    e
    r
    i
    m
    R
    o
    o
    m
    C
    o
    u
    n
    t
    

    View Slide

22. BE UNAMBIGUOUS
    BAD:
    $
    s
    t
    a
    t
    e = '
    a
    c
    t
    i
    v
    e
    '
    ;
    $
    s
    t
    a
    t
    e = '
    N
    e
    w Y
    o
    r
    k
    '
    ;
    GOOD:
    $
    s
    t
    a
    t
    e = '
    a
    c
    t
    i
    v
    e
    '
    ;
    $
    c
    o
    u
    n
    t
    r
    y
    S
    t
    a
    t
    e = '
    N
    e
    w Y
    o
    r
    k
    '
    ;
    

    View Slide

23. FUNCTIONS
    

    View Slide

24. USE VERBS
    BAD:
    $
    l
    i
    s
    t
    -
    >
    r
    e
    f
    e
    r
    e
    n
    c
    e
    C
    o
    u
    n
    t
    (
    )
    ;
    GOOD:
    $
    l
    i
    s
    t
    -
    >
    c
    o
    u
    n
    t
    (
    )
    ;
    $
    l
    i
    s
    t
    -
    >
    c
    l
    e
    a
    r
    (
    )
    ;
    $
    l
    i
    s
    t
    -
    >
    s
    o
    r
    t
    (
    )
    ;
    $
    o
    b
    j
    -
    >
    a
    d
    d
    R
    e
    f
    e
    r
    e
    n
    c
    e
    (
    )
    ;
    

    View Slide

25. KEEP IT SHORT
    BAD:
    $
    l
    i
    s
    t
    -
    >
    g
    e
    t
    N
    u
    m
    b
    e
    r
    O
    f
    I
    t
    e
    m
    s
    (
    )
    ;
    GOOD:
    $
    l
    i
    s
    t
    -
    >
    c
    o
    u
    n
    t
    (
    )
    ;
    

    View Slide

26. BUT NOT TOO SHORT
    BAD:
    $
    l
    i
    s
    t
    -
    >
    v
    e
    r
    i
    f
    y
    (
    )
    ;
    $
    l
    i
    s
    t
    -
    >
    c
    h
    e
    c
    k
    (
    )
    ;
    GOOD:
    $
    l
    i
    s
    t
    -
    >
    c
    o
    n
    t
    a
    i
    n
    s
    N
    u
    l
    l
    (
    )
    ;
    

    View Slide

27. ASK QUESTIONS FOR
    BOOLEANS
    BAD:
    $
    l
    i
    s
    t
    -
    >
    e
    m
    p
    t
    y
    (
    )
    ;
    GOOD:
    $
    l
    i
    s
    t
    -
    >
    i
    s
    E
    m
    p
    t
    y
    (
    )
    ;
    $
    l
    i
    s
    t
    -
    >
    c
    o
    n
    t
    a
    i
    n
    s
    (
    $
    i
    t
    e
    m
    )
    ;
    

    View Slide

28. AVOID REDUNDANCY WITH
    ARGUMENT
    BAD:
    $
    l
    i
    s
    t
    -
    >
    a
    d
    d
    I
    t
    e
    m
    (
    $
    i
    t
    e
    m
    )
    ;
    $
    h
    a
    n
    d
    l
    e
    r
    -
    >
    r
    e
    c
    e
    i
    v
    e
    M
    e
    s
    s
    a
    g
    e
    (
    $
    m
    e
    s
    s
    a
    g
    e
    )
    ;
    GOOD:
    $
    l
    i
    s
    t
    -
    >
    a
    d
    d
    (
    $
    i
    t
    e
    m
    )
    ;
    $
    h
    a
    n
    d
    l
    e
    r
    -
    >
    r
    e
    c
    e
    i
    v
    e
    (
    $
    m
    e
    s
    s
    a
    g
    e
    )
    ;
    

    View Slide

29. AVOID REDUNDANCY WITH
    RECEIVER
    BAD:
    $
    l
    i
    s
    t
    -
    >
    a
    d
    d
    T
    o
    L
    i
    s
    t
    (
    $
    i
    t
    e
    m
    )
    ;
    GOOD:
    $
    l
    i
    s
    t
    -
    >
    a
    d
    d
    (
    $
    i
    t
    e
    m
    )
    ;
    

    View Slide

30. DON'T USE
    “AND” OR “OR”
    BAD:
    $
    m
    a
    i
    l
    -
    >
    v
    e
    r
    i
    f
    y
    A
    d
    d
    r
    e
    s
    s
    A
    n
    d
    S
    e
    n
    d
    S
    t
    a
    t
    u
    s
    (
    )
    ;
    GOOD:
    f
    u
    n
    c
    t
    i
    o
    n u
    p
    d
    a
    t
    e
    A
    d
    d
    r
    e
    s
    s
    (
    ) {
    $
    m
    a
    i
    l
    -
    >
    v
    e
    r
    i
    f
    y
    A
    d
    d
    r
    e
    s
    s
    (
    )
    ;
    $
    m
    a
    i
    l
    -
    >
    s
    e
    n
    d
    S
    t
    a
    t
    u
    s
    (
    )
    ;
    }
    

    View Slide

31. STAY CONSISTENT
    EXAMPLES:
    o
    n
    e =
    > s
    i
    n
    g
    l
    e
    , d
    e
    t
    a
    i
    l
    , p
    a
    r
    t
    , i
    t
    e
    m
    , u
    n
    i
    t
    m
    a
    n
    y =
    > l
    i
    s
    t
    , c
    o
    l
    l
    e
    c
    t
    i
    o
    n
    , p
    l
    u
    r
    a
    l
    c
    r
    e
    a
    t
    e =
    > a
    d
    d
    , i
    n
    s
    e
    r
    t
    , n
    e
    w
    , s
    a
    v
    e
    , m
    a
    k
    e
    r
    e
    m
    o
    v
    e =
    > r
    e
    s
    e
    t
    , u
    n
    s
    e
    t
    , d
    e
    l
    e
    t
    e
    , u
    n
    l
    i
    n
    k
    , d
    r
    o
    p
    GOOD:
    P
    i
    c
    k o
    n
    e a
    n
    d s
    t
    i
    c
    k t
    o i
    t
    !
    

    View Slide

32. CLASSES
    

    View Slide

33. PREFER NOUN PHRASES
    BAD:
    C
    o
    l
    l
    e
    c
    t
    GOOD:
    C
    o
    l
    l
    e
    c
    t
    i
    o
    n
    

    View Slide

34. USE NAMESPACES
    OK:
    S
    y
    s
    t
    e
    m
    O
    n
    l
    i
    n
    e
    M
    e
    s
    s
    a
    g
    e
    BETTER:
    S
    y
    s
    t
    e
    m
    \
    O
    n
    l
    i
    n
    e
    \
    M
    e
    s
    s
    a
    g
    e
    

    View Slide

35. AVOID NULL WORDS
    BAD:
    C
    o
    n
    n
    e
    c
    t
    i
    o
    n
    M
    a
    n
    a
    g
    e
    r
    , X
    m
    l
    H
    e
    l
    p
    e
    r
    O
    b
    j
    e
    c
    t
    D
    a
    t
    a
    H
    a
    n
    d
    l
    e
    r
    M
    a
    n
    a
    g
    e
    r
    B
    u
    i
    l
    d
    e
    r
    H
    e
    l
    p
    e
    r
    F
    a
    c
    t
    o
    r
    y
    $
    t
    m
    p
    , $
    t
    e
    m
    p
    , $
    d
    a
    t
    a
    , $
    v
    a
    r
    , $
    a
    r
    r
    a
    y
    , $
    k
    e
    y
    , .
    .
    .
    GOOD:
    C
    o
    n
    n
    e
    c
    t
    i
    o
    n
    X
    m
    l
    D
    o
    c
    u
    m
    e
    n
    t
    , X
    m
    l
    N
    o
    d
    e
    , e
    t
    c
    .
    

    View Slide

36. SERVICES
    NOUN + VERB + ( “ER” | “OR” )
    

    View Slide

37. EXAMPLES
    Q
    u
    e
    r
    y
    D
    u
    m
    p
    e
    r
    C
    o
    n
    f
    i
    g
    u
    r
    a
    t
    i
    o
    n
    B
    u
    i
    l
    d
    e
    r
    

    View Slide

38. NOUNS
    Attribute, Base, Bridge, Bucket, Chain, Collection,
    Configuration, Context, Command, Composite, Element,
    Entity, Exception, Field, Flag, Flyweight, Identity, Info, Item,
    Key, Method, Node, Null Object, Option, Proxy, Protocol,
    Peer, Query, Record, Service, Strategy, Style, State, Target,
    Template Method, Type, Unit
    

    View Slide

39. NOMINALIZED VERBS
    Adapter, Adjuster, Attacher, Binder, Builder, Calculator,
    Coordinator, Container, Converter, Controller, Connector,
    Collector, Configurer, Constructor, Composer, Commander,
    Creater, Debugger, Decorator, Decider, Designer, Delegator,
    Destroyer, Dispatcher, Dumper, Editor, Executor, Exporter,
    Extractor, Factory, Filter, Formatter, Generator, Initializer,
    Identifier, Interpreter, Inserter, Informer, Importer, Iterator,
    Listener, Limiter, Machine, Marker, Mediator, Memento,
    Matcher, Mapper, Messenger, Mover, Observer, Parser,
    Presenter, Provider, Preparer, Printer, Processor, Receiver,
    Reader, Recorder, Remover, Resolver, Sanitizer, Selector,
    Scheduler, Sender, Serializer, Sorter, Standardizer,
    Supporter, Synchronizer, Tokenizer, Tracer, Tracker,
    Validator, Viewer, Visitor, Writer
    

    View Slide

40. CONCLUSION
    

    View Slide

41. THINKING AHEAD
    > Start with a thing and a context
    

    View Slide

42. REFACTORING
    > Stay meaningful
    

    View Slide

43. PRACTICAL STEPS ...
    Ask what is it supposed to do
    Find out more about the business domain
    Ask a collegue what he thinks it could be called
    Look on GitHub for similar code
    Decide that obvious is best
    

    View Slide

44. Once I’m happy with the names,
    I’m usually happy with the design.
    - Bob Nystrom
    

    View Slide

45. THANK YOU !
    

    View Slide

46. QUESTIONS ?
    

    View Slide

47. PLEASE LEAVE FEEDBACK!
    https://joind.in/13391
    

    View Slide

48. SOURCES
    journal.stuffwithstuff.com
    github.com/AndrewVos/github-statistics
    programmers.stackexchange.com
    globalnerdy.com
    

    View Slide