Clean code:Stop wasting my time<br />February 17, 2011<br />1<br />
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...
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 ...
This talk is about time<br />About your time<br />About my time<br />About the next guys time<br />February 17, 2011<br />...
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 ...
What I would talk about<br />Good documentation means less documentation<br />How does that work for your team<br />Commit...
Stuff you all know about<br />SCM<br />Unit testing<br />Dependency Injection<br />Why we don’t like singletons / static f...
Yay! Samples<br />class myClass {<br />    /**<br />     * Constructor<br />     */<br />    public function __construct()...
Yay! Samples<br />class myClass {<br />    /**<br />     * Create an instance of ‘myClass’<br />     */<br />    public fu...
Yay! Samples<br />class myClass {<br />    /**<br />     * @returnmyClass<br />     */<br />    public function __construc...
Yay! Samples<br />class myClass{<br />    public function __construct() {<br />    }<br />    // methods... <br />}<br />F...
Yay! Samples<br />class myClass{<br />    // methods... <br />}<br />February 17, 2011<br />12<br />
So…<br />Seems mundane? That stuff scales!<br />But everything needs to have a docblock!<br />But I might need it later<br...
DOCUMENT EVERYTHING !!1eleven<br />February 17, 2011<br />14<br />At least that’s what they told me<br />How about that:<b...
Bad code<br />class User {<br />	public function getId() {…}<br />	public function getName() {…}<br />    /** Calculate Bo...
Bettercode<br />class user {<br />	public function getUserId() {…}<br />	public function getFirst/Last/DisplayName() {…}<b...
Again<br />Short and undescriptive function names make it very easy to write documentation<br />Good ones make it hard to ...
Meaningful ? A small example<br />February 17, 2011<br />18<br />class foo {<br />	/**<br />	 * Setter forproperty x<br />...
Consistency ?
Improved readability through uniformity ?</li></li></ul><li>But I NEEEEEEED that<br />No you don’t! <br />We are programme...
Output – It‘s like autoloading<br /><?php<br />/**<br /> * @package module_x<br /> * @subpackage y_z<br /> */<br />/**<br ...
Know your user or coworker<br />February 17, 2011<br />21<br />
This is phpdoc &phpcs valid<br />Well… after the build script<br /><?php<br />class myClass {<br />}<br />*You might need ...
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...
February 17, 2011<br />24<br />abstract class xyzRequest {<br /> /**<br />   * Initializes this xyzRequest.<br />   *<br /...
Another one?<br />/**<br />* Retrieves the uniform resource identifier for the current web request.<br />*<br />* @return ...
Inline Comments<br />$i++ // Increment $i by one<br />Yeah.. we don‘t need to talk about that<br />Can be great, especiall...
Inline Sample<br />public function generateReport() {<br />  // get the db connection<br />  $reg = GlobalStorage::get(“db...
Inline Sample<br />public function generateReport() {<br />  $this->checkAuthentication();<br />  $template = this->create...
No docs are not the answer<br />I‘m not saying BE GONE all documentation<br />Let‘s remove useless comments !<br />Let‘s (...
It‘s not ONLY about the code<br />Commit messages matter !<br />Commit message are like book covers, they raise expectatio...
Commits<br />Yes, this highly depends on your team<br />Fixes #5232<br />Fixes #4523 with the last release the database st...
Git made this worse<br />More smaller commits tend to make people just describe what they do and not why they did it<br />...
To sum up<br />Don’t write documentation you think has no use<br />See if you can substitute documentation with more descr...
Comments?Questions!<br />Anything else?<br />34<br />Volker Dusch <br />@__edorian<br />
Upcoming SlideShare
Loading in...5
×

php unconference Europa: Clean code - Stop wasting my time

26,704

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
1 Comment
5 Likes
Statistics
Notes
No Downloads
Views
Total Views
26,704
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
39
Comments
1
Likes
5
Embeds 0
No embeds

No notes for slide

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 />
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×