The document discusses the importance of writing clean, maintainable code in PHP, emphasizing that programmers should invest time in creating readable code to minimize wasted time for others. It critiques excessive documentation and suggests that code should be self-explanatory, encouraging meaningful naming conventions and effective use of comments. Additionally, it highlights the significance of good commit messages and team collaboration in maintaining code quality.

1. CLEAN CODE: STOP WASTEING MY TIME

2. AboutmeVolker Dusch / @__edorianDoing PHP for ~7 Years nowI‘m sorry for the bullet points, i don‘t know any better. (There will be code, and cake, maybe)Feel free to interrupt me at any time !

3. AboutyouYou seem to be smarty peopleI guess you are motivatedAnd I'm just going to assume you work with smart people you respect

4. This is about timeAbout your timeAbout my timeAbout the next guys time

5. So stop wasting timeTake more time writing code, you are only doing it onceMake everyone waste less time reading code, that happens quite a lotDisclaimer: When saying ‘documentation‘ inever talk about @phpdoc for apis (@param, @return)

6. Oh yeah by that wayI won’t be talking about ’design’ very muchBad design hurts… but you’ll get over it … or at least used to itBad code hurts every day because it sucks differently every time

7. Samples are nextStuff I’d say you all know about:SCMUnit testingDependency InjectionThat Singletons / Statics / Globals are evilOther design mumbo jumbo

8. Yay ! Samples class myClass { /** * Constructor */ public function __construct() { } // methods... }

9. Yay ! Samples class myClass { /** * Create an instance of ‘myClass’ */ public function __construct() { } // methods... }

10. Yay ! Samples class myClass { /** * @return myClass */ public function __construct() { } // methods... }

11. Yay ! Samples class myClass { public function __construct() { } // methods... }

12. Yay ! Samples class myClass { // methods... }

13. So… But everything has to have a docblock ! It‘s in the guidelines !But i might need it later !That's just because it‘s in the template and i didn‘t delete it

14. DOCUMENT EVERYTHING !!1 That's at least what they told meProvocation incoming:Good code is hard document Bad code is easy to document

15. ‘Bad‘ Codeclass user { public function getId() {…} public function getName() {…} /** Calculate Body-Mass-Index @link … */ public function getBMI() {…} /** @param float $kg Weight in Kilogramm */ public function setWeight($weightInKg) {…}

16. ‘Good‘ Codeclass user { public function getUserId() {…} public function getFirst/Last/DisplayName() {…} /** @link … */ public function getBodyMassIndex() {…} /** @param float $kilogramm */ public function setWeight($kilogramm) {…}

17. AgainA short, undescriptive, function name like ‘calc‘ always make it easy to write documentationSadly people will need to read it (again and again ..)

18. Another little exampleclass foo { /** * Setter forproperty x * @paramstring $x */ public function setX($x) { $this->x = $x; }}Why ?Generating API Docs ?

19. Consistency ?

20. Improved readability through uniformity ?But I NEEEED thatWe are programmers, trivial stuff is for the computerIf you need trivial stuff for E_UGLY_REQUIRENMENT_X than automate itSpent time once putting that in your build system

21. This is PHP_CodeSniffer valid Well… after our Doc Prepare<?phpclass myClass {}Yes that breaks your IDEs sniffs

22. Output<?php/** * @package module_x * @subpackage y_z*//** * @package module_x * @subpackage y_z * @since creation_date * @version 1.2.3.4*/class myClass { }

23. Inline Comments$i++ // Increment $i by oneYeah.. we don‘t need to talk about thatCan be great, especially when they tell you ‘WHY‘ something was doneMost time aren‘t that great

24. Inline Samplepublic function generateReport() { // get the db connection $reg = GlobalStorage::get(“db“); // auth if(!$reg->getOne(“SELECT VIEW_REPORT FROM USER ….“)) {…} $id = $reg->getOne(“select … „); // template // render new ReportTemplate($id); // ….

25. Inline Samplepublic function generateReport() { $this->checkAuthentication(); $template = this->createReportTemplate(); $this->renderReport($template);}That's not perfect but the ‘// next block‘ comments are gone

26. No docs are not the answerI‘m not saying BE GONE all documentationLet‘s remove useless comments !Let‘s (maybe ?) agree upon that sometimes there is no USEFULL comment.Know who you write docs for

27. It‘s not ONLY about the codeCommit messages matter !Commit message are like book covers, they raise expectations. The diff should tell a matching story Don’t repeat the obvious, tell why you did it and then show me how in the diff

28. CommitsYes, this highly depends on your teamFixes #5232Fixes #4523 with the last release the database structure changedReworked the Authentication to account for the new SingleSignOnFixed some problemsTidy | phpdoc | cleanup | etc.

29. One Commit – One PurposeStuff you can do:Fix a bugImplement a featureRefractor somethingTidy up some codeStuff I’d like you not to do:

30. More than one of the above at onceTo sum upDon’t write documentation you think has no useSee if you can substitute documentation with more descriptive namingAlways: Do what your team has agreed upon and if you don’t like it try to change it if there is a benefit others see too.

31. ANY MORE QUESTIONS OR COMMENTS ?