Clean Code: Stop wasting my time

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


Total Views
On Slideshare
From Embeds
Number of Embeds



Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

    No notes for slide


  • 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:
    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
    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
    class myClass {
    Yes that breaks your IDEs sniffs
  • 22. Output
    * @package module_x
    * @subpackage y_z
    * @package module_x
    * @subpackage y_z
    * @since creation_date
    * @version
    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() {
    $template = this->createReportTemplate();
    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.