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 full-size 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 full-size 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 full-size slide

  4. WHY ARE WE
    NAMING THINGS ?

    View full-size slide

  5. THING
    +
    CONTEXT
    =
    MEANING

    View full-size slide

  6. GENERAL ADVICES

    View full-size slide

  7. 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 full-size slide

  8. 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 full-size slide

  9. 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 full-size slide

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

    View full-size slide

  11. REALLY, NO UNICODE!
    FUNNY, EH?

    View full-size slide

  12. 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 full-size slide

  13. 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 full-size slide

  14. 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 full-size slide

  15. 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 full-size slide

  16. 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 full-size slide

  17. 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 full-size slide

  18. 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 full-size slide

  19. 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 full-size slide

  20. 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 full-size slide

  21. 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 full-size slide

  22. 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 full-size slide

  23. 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 full-size slide

  24. 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 full-size slide

  25. 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 full-size slide

  26. 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 full-size slide

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

    View full-size slide

  28. 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 full-size slide

  29. 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 full-size slide

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

    View full-size slide

  31. 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 full-size slide

  32. 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 full-size slide

  33. 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 full-size slide

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

    View full-size slide

  35. REFACTORING
    > Stay meaningful

    View full-size slide

  36. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide