Clean Code: Stop wasting my time

CLEAN CODE: STOP WASTEING MY TIME

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 !

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

This is about time
About your time
About my time
About the next guys time

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)

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

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

Yay ! Samples
class myClass {
/**
* Constructor
*/
public function __construct() {
}
// methods...
}

Yay ! Samples
class myClass {
/**
* Create an instance of ‘myClass’
*/
}
// methods...
}

Yay ! Samples
class myClass {
/**
* @return myClass
*/
}
// methods...
}

Yay ! Samples
class myClass {
}
// methods...
}

Yay ! Samples
class myClass {
// methods...
}

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

DOCUMENT EVERYTHING !!1
That's at least what they told me
Provocation incoming:
Good code is hard document
Bad code is easy to document

‘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) {…}

‘Good‘ Code
class user {
public function getUserId() {…}
public function getFirst/Last/DisplayName() {…}
/** @link … */
public function getBodyMassIndex() {…}
/** @param float $kilogramm */
public function setWeight($kilogramm) {…}

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 ..)

Another little example
class foo {
/**
* Setter forproperty x
* @paramstring $x
*/
public function setX($x) {
$this->x = $x;
}
}
Why ?
Generating API Docs ?
Consistency ?
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

This is PHP_CodeSniffer valid
Well… after our Doc Prepare
<?php
class myClass {
}
Yes that breaks your IDEs sniffs

Output
<?php
/**
* @package module_x
* @subpackage y_z
*/
/**
* @package module_x
* @subpackage y_z
* @since creation_date
* @version 1.2.3.4
*/
class myClass { }

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

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); // ….

Inline Sample
public function generateReport() {
$this->checkAuthentication();
$template = this->createReportTemplate();
$this->renderReport($template);
}
That's not perfect but the ‘// next block‘ comments are gone

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

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

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.

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:
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.

ANY MORE QUESTIONS OR COMMENTS ?

THANK YOU FOR YOUR TIME

Clean Code: Stop wasting my time

by Edorian

Accessibility

Categories

Upload Details

Usage Rights

2 Embeds 11

Statistics