April 10, 2023

1

Clean code:Stop wasting my time

April 10, 20232

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!

April 10, 20233

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

April 10, 20234

This talk is about time About your time

About my time

About the next guys time

April 10, 20235

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)

April 10, 20236

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

April 10, 20237

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

April 10, 20238

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

April 10, 20239

Yay! Samplesclass myClass { /** * Create an instance of ‘myClass’ */ public function __construct() { } // methods... }

April 10, 202310

Yay! Samplesclass myClass { /** * @return myClass */ public function __construct() { } // methods... }

April 10, 202311

Yay! Samplesclass myClass {

public function __construct() { } // methods... }

April 10, 202312

Yay! Samplesclass myClass {

// methods... }

April 10, 202313

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

April 10, 202314

DOCUMENT EVERYTHING !!1eleven At least that’s what they told me

How about that:

Good code is hard to documentBad code is easy to document

I prefer good code over a lot of docs

April 10, 202315

Bad codeclass 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)

{…}

April 10, 202316

Better codeclass user {

public function getUserId() {…}public function getFirst/Last/DisplayName() {…}

/** @link … */public function getBodyMassIndex() {…}

/** @param float $kilogramm */public function setWeight($kilogramm) {…}

April 10, 202317

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

April 10, 202318

Meaningful ? A small exampleclass foo {

/** * Setter for property x * @param string $x

*/public function setX($x) {

$this->x = $x;}

}

Why ?

• Generating API Docs ?

• Consistency ?• Improved

readability through uniformity ?

April 10, 202319

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

April 10, 202320

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 { }

April 10, 202321

Know your user or coworker

April 10, 202322

This is phpdoc & phpcs valid Well… after the build script<?php

class myClass {

} *You might need 2 phpcs standards?

April 10, 202323

A final test

See if you can spot the issues

Or just guess what I‘d complain about

April 10, 202324

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()) {

April 10, 202325

Another one?/** * Retrieves the uniform resource identifier for the current web request. * * @return string Unified resource identifier */ public function getUri()

/** * See if the client is using absolute uri * * @return boolean true, if is absolute uri otherwise false */public function isAbsUri()

April 10, 202326

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

April 10, 202327

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

April 10, 202328

Inline Samplepublic function generateReport() { $this->checkAuthentication(); $template = this-

>createReportTemplate(); $this->renderReport($template);}

That's not perfect but the ‘// next block‘ comments are gone

April 10, 202329

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

April 10, 202330

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

April 10, 202331

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.

April 10, 202332

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 cacheTokens attribute Moved code from A to B

April 10, 202333

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.

34

Comments?Questions!Anything else?

Volker Dusch @__edorian

35

Thank your for your timeTell me if you liked it. And tell me if not!)

Volker Dusch @__edorian