Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Naming Things

Naming Things

I gave this talk at the PHPUK15 in London

Anne-Julia Seitz

February 20, 2015
Tweet

More Decks by Anne-Julia Seitz

Other Decks in Programming

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