Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

php unconference Europa: Clean code - Stop wasting my time

27,800 views

Published on

Write less stupid documentation and spent the time writing good code that doesn't need docs.. and some other related stuff

Published in: Technology

php unconference Europa: Clean code - Stop wasting my time

  1. 1. Clean code:Stop wasting my time<br />February 17, 2011<br />1<br />
  2. 2. About me<br />Volker Dusch / @__edorian<br />Doing PHP for ~8 years now<br />I’m sorry for the bullet points, I don’t know any better(There will be code, and cake, maybe)<br />Feel free to interrupt me at any time!<br />February 17, 2011<br />2<br />
  3. 3. About you<br />You seem to be smart people<br />I guess you are motivated<br />And I’m just going to assume that you work with smart people you respect<br />February 17, 2011<br />3<br />
  4. 4. This talk is about time<br />About your time<br />About my time<br />About the next guys time<br />February 17, 2011<br />4<br />
  5. 5. So stop wasting time<br />Don’t make me spend time trying to figure out what you are doing<br />Don’t spend your own time writing stuff that isn’t going to help me anyways<br />A little disclaimer: When I talk about ‘documentation’ I don’t mean @phpdoc tags for api docs (@param & @return)<br />February 17, 2011<br />5<br />
  6. 6. What I would talk about<br />Good documentation means less documentation<br />How does that work for your team<br />Commit messages I LIKE to read<br />Everything related you want to discussIf we don’t make it through the slides I’m happy<br />February 17, 2011<br />6<br />
  7. 7. Stuff you all know about<br />SCM<br />Unit testing<br />Dependency Injection<br />Why we don’t like singletons / static functions and other globals<br />Other design mumbo jumbo<br />If not: Read up on it. There are great resources out there<br />February 17, 2011<br />7<br />
  8. 8. Yay! Samples<br />class myClass {<br /> /**<br /> * Constructor<br /> */<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />February 17, 2011<br />8<br />
  9. 9. Yay! Samples<br />class myClass {<br /> /**<br /> * Create an instance of ‘myClass’<br /> */<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />February 17, 2011<br />9<br />
  10. 10. Yay! Samples<br />class myClass {<br /> /**<br /> * @returnmyClass<br /> */<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />February 17, 2011<br />10<br />
  11. 11. Yay! Samples<br />class myClass{<br /> public function __construct() {<br /> }<br /> // methods... <br />}<br />February 17, 2011<br />11<br />
  12. 12. Yay! Samples<br />class myClass{<br /> // methods... <br />}<br />February 17, 2011<br />12<br />
  13. 13. So…<br />Seems mundane? That stuff scales!<br />But everything needs to have a docblock!<br />But I might need it later<br />That‘s just because it‘s in the template and I didn‘t delete it<br />February 17, 2011<br />13<br />
  14. 14. DOCUMENT EVERYTHING !!1eleven<br />February 17, 2011<br />14<br />At least that’s what they told me<br />How about that:<br /> Good code is hard to document<br /> Bad code is easy to document<br />I prefer good code over a lot of docs<br />
  15. 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 />February 17, 2011<br />15<br />
  16. 16. Bettercode<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 />February 17, 2011<br />16<br />
  17. 17. Again<br />Short and undescriptive function names make it very easy to write documentation<br />Good ones make it hard to write meaningful stuff<br />Sadly people will need to read your docs again and again and again<br />February 17, 2011<br />17<br />
  18. 18. Meaningful ? A small example<br />February 17, 2011<br />18<br />class foo {<br /> /**<br /> * Setter forproperty x<br /> * @param string $x<br /> */<br /> public function setX($x) {<br /> $this->x = $x;<br /> }<br />}<br />Why ?<br /><ul><li>Generating API Docs ?
  19. 19. Consistency ?
  20. 20. Improved readability through uniformity ?</li></li></ul><li>But I NEEEEEEED that<br />No you don’t! <br />We are programmers, trivial stuff is for the computer!<br />If you really need that for E_UGLY_REQUIREMENT than automate it<br />Spent time once putting that into your build<br />Your OSS mileage may vary<br />February 17, 2011<br />19<br />
  21. 21. Output – It‘s like autoloading<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 1.2.3.4<br /> */<br />class myClass { }<br />February 17, 2011<br />20<br />
  22. 22. Know your user or coworker<br />February 17, 2011<br />21<br />
  23. 23. This is phpdoc &phpcs valid<br />Well… after the build script<br /><?php<br />class myClass {<br />}<br />*You might need 2 phpcs standards?<br />February 17, 2011<br />22<br />
  24. 24. A final test<br />See if you can spot the issues<br />Or just guess what I‘d complain about<br />February 17, 2011<br />23<br />
  25. 25. February 17, 2011<br />24<br />abstract class xyzRequest {<br /> /**<br /> * Initializes this xyzRequest.<br /> *<br /> * Available options:<br /> *<br /> * * logging: Whether to enable logging or not (false by default)<br /> *<br /> * @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance<br /> * @param array $parameters An associative array of initialization parameters<br /> * @param array $attributes An associative array of initialization attributes<br /> * @param array $options An associative array of options<br /> *<br /> * @return bool true, if initialization completes successfully, otherwise false<br /> *<br /> * @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest<br /> */<br /> public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {<br />
  26. 26. Another one?<br />/**<br />* Retrieves the uniform resource identifier for the current web request.<br />*<br />* @return string Unified resource identifier<br />*/<br />publicfunctiongetUri()<br />/**<br />* See if the client is using absolute uri<br />*<br />* @return boolean true, if is absolute uri otherwise false<br />*/<br />publicfunctionisAbsUri()<br />February 17, 2011<br />25<br />
  27. 27. 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 />February 17, 2011<br />26<br />
  28. 28. 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 /> // template<br /> $id = $reg->getOne(“select … „); <br /> // render<br /> new ReportTemplate($id); // ….<br />February 17, 2011<br />27<br />
  29. 29. 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 />February 17, 2011<br />28<br />
  30. 30. 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 USEFUL comment.<br />Know who you write docs for<br />February 17, 2011<br />29<br />
  31. 31. 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 />February 17, 2011<br />30<br />
  32. 32. 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 />February 17, 2011<br />31<br />
  33. 33. Git made this worse<br />More smaller commits tend to make people just describe what they do and not why they did it<br />Delete<br />Tweak output<br />Rename variable<br />Add cacheTokensattribute<br />Moved code from A to B<br />February 17, 2011<br />32<br />
  34. 34. 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 />February 17, 2011<br />33<br />
  35. 35. Comments?Questions!<br />Anything else?<br />34<br />Volker Dusch <br />@__edorian<br />
  36. 36. Thank your for your time<br />Tell me if you liked it. And tell me if not!)<br />Volker Dusch <br />@__edorian<br />35<br />

×