Naming Things

I gave this talk at the PHPUK15 in London

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