Languages
Pages
Legal
CLEAN CODE: STOP WASTEING MY
TIME
About me
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 !
About you
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‘ i never 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’
*/
public function __construct() {
}
// methods...
}
Yay ! Samples
class myClass {
/**
* @return myClass
*/
public function __construct() {
}
// methods...
}
Yay ! Samples
class myClass {
public function __construct() {
}
// 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 for property x
* @param string $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 oneYeah.. 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 bugImplement a featureRefractor somethingTidy 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
Top Related