This document discusses the importance of clean code and naming conventions. It argues that naming everything properly, including namespaces, classes, functions and variables, is crucial because people will read code far more than they write it. Descriptive names communicate intent and enable code to be understood without comments. Common naming issues like 'Util' classes and generic names are addressed. The document emphasizes that functions should be named for what they do, with boolean functions starting with 'has' or 'is'. Setters should not return anything other than the object or null.

1. Stop wasting time through clean code#phpnw11Volker Dusch / @__edorian

2. So stop wasting time!Why are we here?2Introduction

3. Why are we hereto talk code and coding!3Introduction

4. });});});4Introduction

5. Me?5Introduction

6. Volker Dusch@__edorian6Introduction

7. PHP for around 9 years 7Introduction

8. I’m currently into TDD, CI, Clean Code and shipping8Introduction…amongst other stuff

9. 9IntroductionJust go and buy those*Book covers used under fair use

10. Get in touchTwitter: @__edorianXing / G+: Volker DuschStackoverflow:(visit us at http://chat.stackoverflow.com/rooms/11/phpIRC: edorianMail: php@wallbash.com10Introduction

11. Ask questions at any time!11IntroductionFirst question gets an elePHPantAnother question gets one too!

12. Why try to save time?12Motivation

13. Because we are professionals13Motivation

14. Even so our field is quite young14Motivation

15. Do you know how expensive it is to have you people around?15Motivation

16. 16MotivationGerman numbers, ymmv€, £, Approx.. valuesYou get around 50k a year50.000 / YearAdding non-wage labor costs of around 60%80.000 / YearOffice space, water, hardware, coffee, plants, cleaning, drugs, travels, training100.000 / Year250 Days without weekends and holidays and your 30 holidays => 220 days455 / DayWhen working 8 hours a day55 Bucks per Hour!Your employer expects you to contribute over 100.000 Bucks in business value per year!

17. Wait why are we here again?17Motivation

18. To get things done, fast!Delivering is fun!18Motivation

19. Coding!19MotivationNot:Requirement engineering,

20. Scrum,

21. Kanban,

22. Organizational structures

23. Sane hardware

24. Sane working environments

25. ToolsWhat do we spent time on?20Time! It matters!

26. 21Time! It matters!Not programmingChangingPlanningThinkingCreatingGrowing/BuildingAskingTypingReviewingReading

27. We spent time:22Time! It matters!Planning

28. Reading

29. Processing

30. Writing

31. Going to 10

32. Actual typing? Not that much23Time! It matters!Your codebase is just likethe database of a websiteRead:Write Ratio - 10:1and brains suck as caches

33. Goals:24Time! It matters!Cheap writesThe ability to change your software quicklyCheap readsThe ability to understand your software quicklyWrites require readsCheap reads25Time! It matters!People will read your code!again and again and again and againDoes it take 5 minutes or 2 hours to understand a module?

34. Why is our code hard to understand?26Clean code?Management?

35. Unclear requirements?

36. Customers?

37. Schedules?

38. Requirement changes?Because WE wrote it like that!We had our reasons but it still is our responsibility!27Clean code?

39. Rushing out stuff to make people happy“Well I’d go back and fix it but I can’t because $x”Is that comfortable?28Clean Code?

40. What we need:29Clean Code?A way to WRITE to our codebase so that we are able to keep our READ costs low!Fearing we might break something leads to us not making necessary changes

41. If we don‘t fix stuff we won‘t have a readable, maintainable codebaseWe need a “Pragmatic” approach for cheap writes30Pragmatic!

42. Pragmatic?31Pragmatic?Fast

43. Simple

44. Just get it done as fast as possible

45. Nobody cares how you do it

46. Micromanagement?‘Pragmatic’ === ‘TDD’32Pragmatic!My boss should NOT have to care about the fact that I’m writing unit tests!

47. If you can go faster when writing tests it is your responsibility to do that!

48. When not writing tests means “getting it done slower” nobody is asking you to do it!I don’t have time to sharpen my axe!There are so many trees that I need to cut down33Pragmatic!

49. This is not a TDD session34TDD! It saves kittens!A small TDD checklist:Write unit tests! TDD is just the fastest way.

50. Just do it. It’s not magic, don’t fear doing it!

51. Practice before you do it at work!

52. Tools? You don‘t need tools to get started!

53. watch –n1 'phpunit' and ¼ of a screen is ALL you need!Get the basics right35TDD! It saves kittens!A small TDD checklist (continued):Aim for 100% test coverage

54. Your tests should run REALLY fast

55. If you can‘t do that now use --filter

56. „You“ means everyone in your team!Writing unit tests is a SKILL36TDD! It saves kittens!You need to acquire it

57. You need to practice

58. It‘s just like any other tool and concept

59. Actually – Unit testing is really easy…

60. Writing testable code can be hard and NEEDS practice!Enough! Code! Now!37Enough! Code! Now!

61. What to focus on?Is there anything we can base our decisions on? 38Enough! Code! Now!

62. 39I <2 off by one errors"There are only two hard problems in Computer Science: cache invalidation, naming things, and off-by-one errors.“- Phil Karlton

63. 40Naming things!

64. We name everythingWe might want to get that right41Naming matters

65. The purpose of a name is to reveal intent42Naming matters

66. A good name tells you everything you need to know!43Examples!class User { public function getId() {…} public function getName() {…} /** Calculate Body-Mass-Index @link … */ public function getBMI() {…} /** @param float $kg Weight in Kilogramm */ public function setWeight($kg) {…}

67. You shouldn’t need comments44Code! Finally!class User { public function getUserId() {…} public function getFirst/Last/DisplayName() {…} /** @link … */ public function getBodyMassIndex() {…} /** @param float $kilogramm */ public function setWeight($kilogramm) {…}

68. Names already arecompliable documentation45Naming matters

69. Another example46Code!class Calendar { public function getMonth($shortened = false) {…}}class Calendar { public function getMonthNames() {…} public function getShortendMonthNames() {…}}

70. Proper naming is important and easily neglectable47Names matter! A lot!Descriptive names communicate intent

71. They enable us to understand what‘s up

72. Misleading names can make it nearly impossible to navigate in a codebaseIt is easy to write code that a machine understands48Names matter! A lot!Writing code that ANOTHER human can understand is A LOT harder

73. Before we startnaming things49Let’s go!

74. 50$pszError = &“E_FATAL\0“;Hungarian Notation?$aArray; $sString; $fFloat; $cCount;interface IUser {} class CUser {}For classes and interfaces we have IDEs

75. If you have long methods you might be interested in types 100 lines later

76. But that isn‘t the issue we want to adressLet’s name things!51Name everything!Namespaces

77. Classes

78. Functions

79. VariablesNamespaces52Name Namespaces!The things that come before the last underscore of your class name

80. Namespaces gave us the ability to get pretty class names

81. “User” vs“Framework_Util_Stuff_Foo_Auth_User”Namespaces53PSR-0The PHP world has mostly agreed that Namespaces  Directory structure

82. Is that a good idea?

83. Harder to change folder structure

84. Duplicate information

85. Just do it anyways. It’s the expected layout

86. It also pushes you to create modules!Classes54Classy class namesThe class name is the single most important definition of what fits into that class

87. Using generic names throws that away!

88. ApplicationManager, FrameworkDataInformationProvider, UtilityDataProcessorOne class, one purpose55Putting the “S” in “SOLID”Name it after its purpose

89. Single responsibility principle!

90. There should be only one reason to change a classProper class namesrelate to good methods56It’s good if it doesn’t fit!Think of the real world$user->getStoreDiscount() ?$userManager->getStoreDiscount(); ?Do we ask your customers how much they owe us or do we keep track of that?Proper class nameslead to smaller classes57Focus!Should we let our Email class figure out attachment mime types?

91. By always asking if stuff fits we can ‘discover’ new classes in our applications

92. EmailAttachment, ImageEmailAttachment?And we care because?58OOP is there to help us!Big classes rob you of all OO benefits

93. You depend on way to much other stuff

94. Usually tightly coupled

95. You can extend from those classes and chances are you can’t swap out ether

96. You don’t get nice interfaces as wellA logger interface59Loggers log!interface Logger { public function log($message);}

97. Composite?60Another logger interfaceinterface Logger { public function log($logMessage); public function setOutputFormat($format); public function activate(); public function deactivate(); public function flush();public function setIncludeTimestamp($format); public function addLogger(Logger $logger);}

98. All those rules! I want to get things done!61Rule 1: Segmentation faultThese are just guidelines

99. They exist to act as early warning signs

100. Not running into trouble two hours later can save an amazing amount of time62‘Util’ is the new ‘Manager’Util Because naming is harddjango/core/files/utils.pydjango/core/mail/utils.pydjango/db/backends/util.pydjango/db/utils.pydjango/forms/util.pydjango/http/utils.pydjango/test/utils.pydjango/utils/... (django still rocks btw.)

101. Reserved class names63Name everything!Some names already have meaning

102. If you name stuff like a design pattern you’d better implement that pattern!

103. Factory, DataMapper, Visitor, Composite, Strategy, Builder

104. A Logger without a log function?Functions!64Best thing since LJMPFirst unit of organization

105. Functions are where the action is

106. For a long time functions where all we had!

107. Calling one got A LOT faster over the yearsFunction naming 65Starting off easyDoes it return a boolean?

108. Call it hasX or isX66Implementation detailsHidden booleans$status = $user->getStatus();if($status == $user::STATUS_BANNED) {}if($user->isBanned()) {}

109. Getters and Setters67setTitle($this);Getter retrieve internal state

110. Setters modify internal state

111. Both should not modify anything else

112. Don’t make your setters into liarsSetters return null!68setTitle($this);Or maybe $this but nothing else!

113. Return codes for ugly IFs onto consumersif(!$config->set("key", "value")) {}if(!$config->has("key")) { $config->set("key", "value");}

114. No boolean parameters69$user->setInactive(false);If you don’t have a very good reason!$user->setAdminStatus(false);$user->setAdminStatus(true);vs$user->revokeAdminRights();$user->grantAdminRights();

115. Classes are nounsFunctions start with verbs!70$title->show();->createStuff(); ->deleteStuff()->dispatchCall(); ->subscribeUser();But never$user->admin(); or $user->bag();$list->subscription();

116. Agree on verbs for actions71Don’t $dir->expunge();Can you tell me the difference between$directory->delete($entry);And$directory->remove($entry);$router->dispatch/delegate($call);$list->add/append($user);

117. Different actions need distinguishable names!72Name everything!Even if that makes function names longer

118. Usually those functions get created for “doing the same thing with different side effects but not wanting to call it that”

119. If you can agree upon terms with your team that’s even better!Always favor longfunction names? NO!73Bigger is not always betterA short an precise public API is important

120. But you want long privates$user->setUserNameOrThrowAn\ExceptionIfNotPossible();$logger->logMessageButDontDoAnything\IfYouCantWriteToTheBackend($message);Not even: $logger->logMessage($message);

121. Public functions will be called from many places74Bigger is not always betterThey should do one thing and maybe throw an exception if they can’t do that

122. Precise names help a lot to create readable client code

123. Interally used functions can be named as verbosely as needed to communicate their intent and behaviorReadable classes75implements humanReadableSome state

124. Lots of small descripte methods

125. Best arranged in order of interestReadable classes?76sort($this) stuff outclass Log { private function writeToLogfile() {} private functionflushCurrentLogfileBuffer(){} public function log($message) {} private isLogfileWriteable {} public function __construct(SplFileInfo$logfile) {} private createLogfileIfNecaccary() {}}

126. Method ordering77usortFirst you build it

127. Then you call it

128. Then it does work

129. Most work happens in private methodsReadable classes?78sorted($this)class Log { public function __construct(SplFileInfo$logfile) {} public functionlog {} private functionisLogfileWriteable{} private function createLogfileIfNecaccary() {} private functionwriteToLogfile() {} private functionflushCurrentLogfileBuffer(){}}

130. Maximum function length?79Name everything!LOC of the function body?

131. Do you like reading functions that are:

132. Over 100?

133. Over 20?

134. Over 7?6 Lines ought to be enough for everybody?80Reading > WritingDoing only one thing shouldn’t take much space

135. Can you split it into 2 functions? Then do!Why long function bodies?81main::doEverything();It’s very easy to create

136. You just have to worry about functionality82Implements unreadableWhat is in a long function?Local variables and code that operates on thempublic function log($message) {$log = ''; $errors = array(); $log .= PHP_EOL . date('Y-m-d H:i:s') . ': '; if(!$message) { $errrors[] = 'No Message'; } else { $log .= $message; } if(!fwrite($this->log)) { $errors[] = 'Write E'; } return $errros;} // I'm really 12 lines long

137. State and operations?83We shall name it TimmyIt’s a class!

138. Long functions are where classes hide!

139. Even in the small example we could separate Log and LogFileWriterFunction overflow?84Methods everywhere!Good thing they have nice names

140. And we wrapped them in classes

141. That’s good for read/write access!

142. Calling overhead just doesn’t matterSmaller is harder to write85Wrapping up functionsWriting ONLY small functions is a SKILL

143. It is _easy_ to write big functions!

144. But the first change makes it all worth!

145. If everything is small it can even impact your coding standard ;) Last thing to nameVariables86We shall name it TimmyRules of thumb:

146. Descriptive function parameters

147. Big scope: long name

148. Short scope: short nameExample87We shall name it Timmyfor($i = 7; $i; --$i) { $this->doStuffToListItem($i);} vsfor($currentlistItemId = 7; $this->listItemIdIsValid($currentlistItemId); --$currentlistItemId) { $this->doStuffToListItem($currentlistItemId);}

149. Descriptive members!88Class scope is big scope!Members are accessed from many places. They should communicate intent!

150. Local variables in small classes are only used twice or thrice89Names matterWrapping up naming"A name, like an honorable human, should say what it means and mean what it says”Names are the basis of our communication!They can speed up things immensely!

151. Arrays90Hash maps everywhere!PHP is hash-map-based programming

152. Our constants are in hash maps

153. Our variables are stored in hash maps

154. Our arrays are hash maps

155. We’d like to foreach over EVERYTHING!

156. PHP Arrays let us create amazing data structures without much hassle91Hash maps everywhere!ArraysPHP Arrays also let us create amazingly complex and unmaintainable data structures$config['user'][$user['id']]['languages']['native'] ='en';But arrays are too way cool to not use them.Maybe we need OOP arrays?

157. Value objects!92New them everywhere!OOP Data structure

158. You can create them everywhere, no DI!

159. Identity is based on state! Think dates

160. Lots of getters and setters. If you really miss arrays you can implement ArrayAccess too

161. http://misko.hevery.com/2008/09/30/to-new-or-not-to-new/

162. Implement IteratorAggregate and you get foreach back!Value objects!93New them everywhere!class List implementsIteratorAggregate, Countable {protected $list= array();publicfunctionadd($item) { $this->list[] = $item; }publicfunctioncount() { returncount($this->list); }publicfunctionremove($index) { if(!isset($this->list[$index])) {/* throw ... */ }unset($this->list[$index]); $this->list = array_merge($this->list); }publicfunctiongetIterator { returnnewArrayIterator($this->list); }}

163. Value objects!94New them everywhere!classMonthlyValuesimplementsIteratorAggregate {protected $values = array();publicfunction __construct(array $values) {if(count($values) != 12) {thrownnewInvalidArgumentException('...'); } $this->values = $values; }publicfunctionget($monthNumber) {return $this->values[$monthNumber]; } // ... publicfunctiongetIterator() ...

164. Comments95New them everywhere!I’ve spend a lot of time ranting about comments. Name things properly!

165. Additional Resources:

166. http://edorian.posterous.com/they-told-you-to-document-everything-they-lie

167. http://www.slideshare.net/Edorian/php-unconference-europa-clean-code-stop-wasting-my-time96Find the method bodyabstract class xyzRequest { /** * Initializes this xyzRequest. * * Available options: * * * logging: Whether to enable logging or not (false by default) * * @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance * @param array $parameters An associative array of initialization parameters * @param array $attributes An associative array of initialization attributes * @param array $options An associative array of options * * @return bool true, if initialization completes successfully, otherwise false * * @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest */ public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {

168. 97Name everything!Error handlingIs a big topic that requires a whole session

169. Just use exceptions in favor of return codes

170. Don‘t force IF statements in client code$stuff = $factory->create('unkownStuff');$stuff->doWork(); // E_FATAL?Enable consumers to handle errors at a point of their choosing!Professionals deliver!98Wrapping upTesting makes you FASTER!

171. Creating small functions saves time!

172. Only tested code can stay clean

173. You can only fix what you can reproduce!

174. JUST – DO – IT! YOU – ARE – IN – CHARGE!99Thanks a lot!Thank you for your time!Slides will be at: http://joind.in/3600the link will be at @__edorian too ;)Please leave me feedback!

175. Recommended Reads100Rate my talk please!Clean CodeManagementProfessionalism^ Best book in 2011 ^In my humble opinion*Book covers used under fair useMore:https://www.google.com/bookmarks/l#!threadID=GU46RJYjEsMU%2FBDcqV3woQ8eH4sOcl