NAMING THINGS THE ART OF WRITING MEANINGFUL CODE FEBRUARY 2015 PHPUK15 

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 

We create solutions for teachers and students to promote writing, research and critical thinking skills, which are instrumental for success in school and career. 

WHY ARE WE NAMING THINGS ? 

ASSEMBLY 

ROCK ART 

CONTEXT 

THING + CONTEXT = MEANING 

GENERAL ADVICES 

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 ( ) 

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 

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 ! 

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

REALLY, NO UNICODE! FUNNY, EH? 

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 ! 

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 

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 

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 

VARIABLES 

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 

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 

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 ' ; 

FUNCTIONS 

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 ( ) ; 

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 ( ) ; 

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 ( ) ; 

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 ) ; 

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 ) ; 

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 ) ; 

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 ( ) ; } 

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 ! 

CLASSES 

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

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 

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 . 

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

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 

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 

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 

CONCLUSION 

THINKING AHEAD > Start with a thing and a context 

REFACTORING > Stay meaningful 

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 

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

THANK YOU ! 

QUESTIONS ? 

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

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