Clean Code: Stop wasting my time

  • 2,382 views
Uploaded on

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

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 !

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
2,382
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
15
Comments
0
Likes
3

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. CLEAN CODE: STOP WASTEING MY TIME
  • 2. Aboutme
    Volker Dusch / @__edorian
    Doing PHP for ~7 Years now
    I‘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. Aboutyou
    You seem to be smarty people
    I guess you are motivated
    And I'm just going to assume you work with smart people you respect
  • 4. This is about time
    About your time
    About my time
    About the next guys time
  • 5. So stop wasting time
    Take more time writing code, you are only doing it once
    Make everyone waste less time reading code, that happens quite a lot
    Disclaimer: When saying ‘documentation‘ inever talk about @phpdoc for apis (@param, @return)
  • 6. Oh yeah by that way
    I won’t be talking about ’design’ very much
    Bad design hurts… but you’ll get over it … or at least used to it
    Bad code hurts every day because it sucks differently every time
  • 7. Samples are next
    Stuff I’d say you all know about:
    SCM
    Unit testing
    Dependency Injection
    That Singletons / Statics / Globals are evil
    Other 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 me
    Provocation incoming:
    Good code is hard document
    Bad code is easy to document
  • 15. ‘Bad‘ Code
    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($weightInKg) {…}
  • 16. ‘Good‘ Code
    class user {
    public function getUserId() {…}
    public function getFirst/Last/DisplayName() {…}
    /** @link … */
    public function getBodyMassIndex() {…}
    /** @param float $kilogramm */
    public function setWeight($kilogramm) {…}
  • 17. Again
    A short, undescriptive, function name like ‘calc‘ always make it easy to write documentation
    Sadly people will need to read it (again and again ..)
  • 18. Another little example
    class 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 that
    We are programmers, trivial stuff is for the computer
    If you need trivial stuff for E_UGLY_REQUIRENMENT_X than automate it
    Spent time once putting that in your build system
  • 21. This is PHP_CodeSniffer valid
    Well… after our Doc Prepare
    <?php
    class 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 one
    Yeah.. we don‘t need to talk about that
    Can be great, especially when they tell you ‘WHY‘ something was done
    Most time aren‘t that great
  • 24. Inline Sample
    public 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 Sample
    public 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 answer
    I‘m not saying BE GONE all documentation
    Let‘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 code
    Commit 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. Commits
    Yes, this highly depends on your team
    Fixes #5232
    Fixes #4523 with the last release the database structure changed
    Reworked the Authentication to account for the new SingleSignOn
    Fixed some problems
    Tidy | phpdoc | cleanup | etc.
  • 29. One Commit – One Purpose
    Stuff you can do:
    Fix a bug
    Implement a feature
    Refractor something
    Tidy up some code
    • Stuff I’d like you not to do:
    • 30. More than one of the above at once
  • To sum up
    Don’t write documentation you think has no use
    See if you can substitute documentation with more descriptive naming
    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.
  • 31. ANY MORE QUESTIONS OR COMMENTS ?
  • 32. THANK YOU FOR YOUR TIME