php unconference Europa: Clean code - Stop wasting my time

Clean code:Stop wasting my time
February 17, 2011
1

About me
Volker Dusch / @__edorian
Doing PHP for ~8 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!
February 17, 2011
2

About you
You seem to be smart people
I guess you are motivated
And I’m just going to assume that you work with smart people you respect
February 17, 2011
3

This talk is about time
About your time
About my time
About the next guys time
February 17, 2011
4

So stop wasting time
Don’t make me spend time trying to figure out what you are doing
Don’t spend your own time writing stuff that isn’t going to help me anyways
A little disclaimer: When I talk about ‘documentation’ I don’t mean @phpdoc tags for api docs (@param & @return)
February 17, 2011
5

What I would talk about
Good documentation means less documentation
How does that work for your team
Commit messages I LIKE to read
Everything related you want to discussIf we don’t make it through the slides I’m happy
February 17, 2011
6

Stuff you all know about
SCM
Unit testing
Dependency Injection
Why we don’t like singletons / static functions and other globals
Other design mumbo jumbo
If not: Read up on it. There are great resources out there
February 17, 2011
7

Yay! Samples
class myClass {
/**
* Constructor
*/
public function __construct() {
}
// methods...
}
February 17, 2011
8

Yay! Samples
class myClass {
/**
* Create an instance of ‘myClass’
*/
}
// methods...
}
February 17, 2011
9

Yay! Samples
class myClass {
/**
* @returnmyClass
*/
}
// methods...
}
February 17, 2011
10

Yay! Samples
class myClass{
}
// methods...
}
February 17, 2011
11

Yay! Samples
class myClass{
// methods...
}
February 17, 2011
12

So…
Seems mundane? That stuff scales!
But everything needs to have a docblock!
But I might need it later
That‘s just because it‘s in the template and I didn‘t delete it
February 17, 2011
13

DOCUMENT EVERYTHING !!1eleven
February 17, 2011
14
At least that’s what they told me
How about that:
Good code is hard to document
Bad code is easy to document
I prefer good code over a lot of docs

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) {…}
February 17, 2011
15

Bettercode
class user {
public function getUserId() {…}
public function getFirst/Last/DisplayName() {…}
/** @link … */
public function getBodyMassIndex() {…}
/** @param float $kilogramm */
public function setWeight($kilogramm) {…}
February 17, 2011
16

Again
Short and undescriptive function names make it very easy to write documentation
Good ones make it hard to write meaningful stuff
Sadly people will need to read your docs again and again and again
February 17, 2011
17

Meaningful ? A small example
February 17, 2011
18
class foo {
/**
* Setter forproperty x
* @param string $x
*/
public function setX($x) {
$this->x = $x;
}
}
Why ?
Generating API Docs ?
Consistency ?
Improved readability through uniformity ?

But I NEEEEEEED that
No you don’t!
We are programmers, trivial stuff is for the computer!
If you really need that for E_UGLY_REQUIREMENT than automate it
Spent time once putting that into your build
Your OSS mileage may vary
February 17, 2011
19

Output – It‘s like autoloading
<?php
/**
* @package module_x
* @subpackage y_z
*/
/**
* @package module_x
* @subpackage y_z
* @since creation_date
* @version 1.2.3.4
*/
class myClass { }
February 17, 2011
20

Know your user or coworker
February 17, 2011
21

This is phpdoc &phpcs valid
Well… after the build script
<?php
class myClass {
}
*You might need 2 phpcs standards?
February 17, 2011
22

A final test
See if you can spot the issues
Or just guess what I‘d complain about
February 17, 2011
23

February 17, 2011
24
abstract class xyzRequest {
/**
* Initializes this xyzRequest.
*
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
*
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
*
* @return bool true, if initialization completes successfully, otherwise false
*
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {

Another one?
/**
* Retrieves the uniform resource identifier for the current web request.
*
* @return string Unified resource identifier
*/
publicfunctiongetUri()
/**
* See if the client is using absolute uri
*
* @return boolean true, if is absolute uri otherwise false
*/
publicfunctionisAbsUri()
February 17, 2011
25

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
February 17, 2011
26

Inline Sample
public function generateReport() {
// get the db connection
$reg = GlobalStorage::get(“db“);
// auth
if(!$reg->getOne(“SELECT view_report FROM USER ….“)) {…}
// template
$id = $reg->getOne(“select … „);
// render
new ReportTemplate($id); // ….
February 17, 2011
27

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

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 USEFUL comment.
Know who you write docs for
February 17, 2011
29

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
February 17, 2011
30

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.
February 17, 2011
31

Git made this worse
More smaller commits tend to make people just describe what they do and not why they did it
Delete
Tweak output
Rename variable
Add cacheTokensattribute
Moved code from A to B
February 17, 2011
32

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.
February 17, 2011
33

Comments?Questions!
Anything else?
34
Volker Dusch
@__edorian

Thank your for your time
Tell me if you liked it. And tell me if not!)
Volker Dusch
@__edorian
35

php unconference Europa: Clean code - Stop wasting my time

by Edorian on Feb 19, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

2 Embeds 23

Statistics

php unconference Europa: Clean code - Stop wasting my time — Presentation Transcript

http://blog.dmr-solutions.com	22
http://twitter.com	1