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. 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
  2. We create solutions for teachers and students to promote writing,

    research and critical thinking skills, which are instrumental for success in school and career.
  3. 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 ( )
  4. 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
  5. 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 !
  6. DON'T USE UNICODE BAD: क = 1 ; कु ल

    = 0 ; जब तक क छोटा है 1 0 से { कु ल + = क; } ALSO BAD: p u b l i c e n u m Т о в а р ы { Т е т р а д и = 2 , К а р а н д а ш и = 4 , В с ё = Т е т р а д и | К а р а н д а ш и }
  7. 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 !
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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 ' ;
  14. 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 ( ) ;
  15. 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 ( ) ;
  16. 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 ( ) ;
  17. 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 ) ;
  18. 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 ) ;
  19. 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 ) ;
  20. 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 ( ) ; }
  21. 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 !
  22. PREFER NOUN PHRASES BAD: C o l l e c

    t GOOD: C o l l e c t i o n
  23. 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
  24. 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 .
  25. 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
  26. 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
  27. 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
  28. 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