Clean Code: Stop wasting my time


Published on

Let us spend less time writing trivial stuff and more time focusing on great code that doesn't need documentation to be understood.
Save other peoples time by writing less !

Published in: Technology

Clean Code: Stop wasting my time

  2. Aboutme<br />Volker Dusch / @__edorian<br />Doing PHP for ~7 Years now<br />I‘m sorry for the bullet points, i don‘t know any better.<br /> (There will be code, and cake, maybe)<br />Feel free to interrupt me at any time !<br />
  3. Aboutyou<br />You seem to be smarty people<br />I guess you are motivated<br />And I'm just going to assume you work with smart people you respect<br />
  4. This is about time<br />About your time<br />About my time<br />About the next guys time<br />
  5. So stop wasting time<br />Take more time writing code, you are only doing it once<br />Make everyone waste less time reading code, that happens quite a lot<br />Disclaimer: When saying ‘documentation‘ inever talk about @phpdoc for apis (@param, @return)<br />
  6. Oh yeah by that way<br />I won’t be talking about ’design’ very much<br />Bad design hurts… but you’ll get over it … or at least used to it<br />Bad code hurts every day because it sucks differently every time<br />
  7. Samples are next<br />Stuff I’d say you all know about:<br />SCM<br />Unit testing<br />Dependency Injection<br />That Singletons / Statics / Globals are evil<br />Other design mumbo jumbo<br />
  8. Yay ! Samples <br />class myClass {<br /> /**<br /> * Constructor<br /> */<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />
  9. Yay ! Samples <br />class myClass {<br /> /**<br /> * Create an instance of ‘myClass’<br /> */<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />
  10. Yay ! Samples <br />class myClass {<br /> /**<br /> * @return myClass<br /> */<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />
  11. Yay ! Samples <br />class myClass {<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />
  12. Yay ! Samples <br />class myClass {<br /> // methods... <br />}<br />
  13. So… <br />But everything has to have a docblock ! It‘s in the guidelines !<br />But i might need it later !<br />That's just because it‘s in the template and i didn‘t delete it<br />
  14. DOCUMENT EVERYTHING !!1 <br />That's at least what they told me<br />Provocation incoming:<br />Good code is hard document <br />Bad code is easy to document<br />
  15. ‘Bad‘ Code<br />class user {<br /> public function getId() {…}<br /> public function getName() {…}<br /> /** Calculate Body-Mass-Index @link … */<br /> public function getBMI() {…}<br /> /** @param float $kg Weight in Kilogramm */<br /> public function setWeight($weightInKg) {…}<br />
  16. ‘Good‘ Code<br />class user {<br /> public function getUserId() {…}<br /> public function getFirst/Last/DisplayName() {…}<br /> /** @link … */<br /> public function getBodyMassIndex() {…}<br /> /** @param float $kilogramm */<br /> public function setWeight($kilogramm) {…}<br />
  17. Again<br />A short, undescriptive, function name like ‘calc‘ always make it easy to write documentation<br />Sadly people will need to read it (again and again ..)<br />
  18. Another little example<br />class foo {<br /> /**<br /> * Setter forproperty x<br /> * @paramstring $x<br /> */<br /> public function setX($x) {<br /> $this->x = $x;<br /> }<br />}<br />Why ?<br /><ul><li>Generating API Docs ?
  19. Consistency ?
  20. Improved readability through uniformity ?</li></li></ul><li>But I NEEEED that<br />We are programmers, trivial stuff is for the computer<br />If you need trivial stuff for E_UGLY_REQUIRENMENT_X than automate it<br />Spent time once putting that in your build system<br />
  21. This is PHP_CodeSniffer valid <br />Well… after our Doc Prepare<br /><?php<br />class myClass {<br />}<br />Yes that breaks your IDEs sniffs<br />
  22. Output<br /><?php<br />/**<br /> * @package module_x<br /> * @subpackage y_z<br />*/<br />/**<br /> * @package module_x <br /> * @subpackage y_z<br /> * @since creation_date<br /> * @version<br />*/<br />class myClass { }<br />
  23. Inline Comments<br />$i++ // Increment $i by one<br />Yeah.. we don‘t need to talk about that<br />Can be great, especially when they tell you ‘WHY‘ something was done<br />Most time aren‘t that great<br />
  24. Inline Sample<br />public function generateReport() {<br /> // get the db connection<br /> $reg = GlobalStorage::get(“db“);<br /> // auth<br /> if(!$reg->getOne(“SELECT VIEW_REPORT FROM USER ….“)) {…}<br /> $id = $reg->getOne(“select … „); // template<br /> // render<br /> new ReportTemplate($id); // ….<br />
  25. Inline Sample<br />public function generateReport() {<br /> $this->checkAuthentication();<br /> $template = this->createReportTemplate();<br /> $this->renderReport($template);<br />}<br />That's not perfect but the ‘// next block‘ comments are gone<br />
  26. No docs are not the answer<br />I‘m not saying BE GONE all documentation<br />Let‘s remove useless comments !<br />Let‘s (maybe ?) agree upon that sometimes there is no USEFULL comment.<br />Know who you write docs for<br />
  27. It‘s not ONLY about the code<br />Commit messages matter !<br />Commit message are like book covers, they raise expectations. The diff should tell a matching story <br />Don’t repeat the obvious, tell why you did it and then show me how in the diff<br />
  28. Commits<br />Yes, this highly depends on your team<br />Fixes #5232<br />Fixes #4523 with the last release the database structure changed<br />Reworked the Authentication to account for the new SingleSignOn<br />Fixed some problems<br />Tidy | phpdoc | cleanup | etc.<br />
  29. One Commit – One Purpose<br />Stuff you can do:<br />Fix a bug<br />Implement a feature<br />Refractor something<br />Tidy up some code<br /><ul><li>Stuff I’d like you not to do:
  30. More than one of the above at once</li></li></ul><li>To sum up<br />Don’t write documentation you think has no use<br />See if you can substitute documentation with more descriptive naming<br />Always: 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.<br />