Naming Things

Naming Things

I gave this talk at the PHPUK15 in London

5fcfa864ae04004e92416a5ea05d5ffa?s=128

Anne-Julia Seitz

February 20, 2015
Tweet

Transcript

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

    PHPUK15
  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
  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.
  4. WHY ARE WE NAMING THINGS ?

  5. ASSEMBLY

  6. ROCK ART

  7. CONTEXT

  8. THING + CONTEXT = MEANING

  9. GENERAL ADVICES

  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 ( )
  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
  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 !
  13. DON'T USE UNICODE BAD: क = 1 ; कु ल

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

  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 !
  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
  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
  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
  19. VARIABLES

  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
  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
  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 ' ;
  23. FUNCTIONS

  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 ( ) ;
  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 ( ) ;
  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 ( ) ;
  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 ) ;
  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 ) ;
  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 ) ;
  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 ( ) ; }
  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 !
  32. CLASSES

  33. PREFER NOUN PHRASES BAD: C o l l e c

    t GOOD: C o l l e c t i o n
  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
  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 .
  36. SERVICES NOUN + VERB + ( “ER” | “OR” )

  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
  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
  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
  40. CONCLUSION

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

  42. REFACTORING > Stay meaningful

  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
  44. Once I’m happy with the names, I’m usually happy with

    the design. - Bob Nystrom
  45. THANK YOU !

  46. QUESTIONS ?

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

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