WJstandards

een-goede-standaard.rst

Waarom een standaard?

Een standaard zorgt ervoor dat alles in je script er hetzelfde uitziet. Dit zorgt voor een vertrouwd gevoel en een overzichtelijk script.

Om het in een live voorbeeld te zien:

// zonder standaard
if($bar == 'foo') {
    echo 'Foo!';
}
elseif  ('baz' == $bar) 
{
  echo 'Baz!';
} else
{
    foreach($baz as $b) {
        echo("$b Bar!");
}}

// met standaard
if ('foo' == $bar) {
    echo 'Foo!';
} else if ('baz' == $bar) {
    echo 'Baz!';
} else {
    foreach ($baz as $b) {
        echo $b.' Bar!';
    }
}

Een standaard schept orde en helpt je met debuggen. Je weet welke eind-accolade bij welke begin-accolade hoort.

Een goede standaard

Consistentie

Een standaard zorgt voor een consistente code. Naast dat door een standaard alles hetzelfde wordt weergegeven hoort er naar mijn mening ook consistentie te zijn in de standaard zelf. Neem nou de if condities. Hoe gaan we die weergeven?

if ($actual == 'expected')
// of
if ('expected' == $actual)

Bij heel veel PHP scripts zie je de eerste versie. Als je echter met test driven development begint en bijvoorbeeld PHPunit gaat gebruiken krijg je dit:

$this->assertEqual('expected', $actual);

Hier zien we dan een inconsistentie in de code. Waar je in de klasse als eerst de actual waarde zet en daarna de expected gebruik je in de testklasse eerst de expected waarde en dan de actual. Als we het andersom draaien krijgen we een eenheid in de code en zorgen we dat we meteen kunnen zien wat we verwachten en wat de waarde is waarin we dit verwachten.

Leesbaarheid

Een goede standaard zorgt ook voor een leesbare code. Leesbaar is een relatief begrip, maar in het algemeen kun je er wel een paar dingen over kwijt. Leesbaar zorgt ervoor dat je verschil ziet tussen verschillende typen in PHP. Een voorbeeld:

if($conditie) {
    echo('foo');

    $bar = substr($conditie, -6);
}

Hier zien we 3 verschillende soorten. We hebben de statements (if, else, function, foreach, ect.), language constructs (echo, require) en de gewone functies (substr, isset, ect.). Dit zijn echt 3 verschillende dingen, maar in de code hierboven lijken ze allemaal hetzelfde. Als we ze nou eens anders weergeven kunnen we in 1 seconde zien wat voor soort het is:

if ($conditie) {
    echo 'foo';

    $bar = substr($conditie, -6);
}

Hier geven we alle statements een spatie tussen de statement naam en het haakje mee, alle language constructs geen haakjes en de functies laten we hetzelfde.

Overzicht

Als laatst zorgt een standaard ook voor overzicht. Overzicht is een mooi begrip dat tussen een brei van letters en cijfers en een brei van lege ruimte zit. Je moet de ultieme combinatie vinden. Neem nou een klasse:

class A {
    public function b($c) {
        if ($d == $e) {
            echo $f ? $e : $c;
        }
        $g = explode($h, $a);
        foreach ($g as $i) {
            echo $i.$j;
        }
    }
}

Dit ziet er beest aardig uit, alles lekker consistent en leesbaar. Alleen alles staat zo dicht op elkaar, je hebt niet echt overzicht. Als we wat lege regels ertussen stoppen ziet het er al 10 keer beter uit:

class A 
{
    public function b($c)
    {
        if ($d == $e) {
            echo $f ? $e : $c;
        }

        $g = explode($h, $a);
        foreach ($g as $i) {
            echo $i.$j;
        }
    }
}

Natuurlijk kun je ook overdrijven, waardoor je hele lange bestanden krijgt met meer whitespace dan code. Dat vind ik ook weer niet de bedoeling.

Een ander voorbeeld is bijv. bij use statements. Dit stukje heb ik gekopieerd uit de Symfony source (en een beetje door elkaar gewikkeld):

use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Sensio\Bundle\GeneratorBundle\Generator\BundleGenerator;
use Symfony\Component\HttpKernel\KernelInterface;
use Symfony\Component\Console\Input\InputInterface;
use Sensio\Bundle\GeneratorBundle\Manipulator\KernelManipulator;
use Symfony\Component\Console\Output\Output;
use Sensio\Bundle\GeneratorBundle\Command\Helper\DialogHelper;
use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
use Sensio\Bundle\GeneratorBundle\Manipulator\RoutingManipulator;

Je bent ook hier het volledige overzicht kwijt. Als je alles nog een beetje sorteerd krijg je al een beter overzicht:

use Symfony\Component\Console\Output\Output;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\HttpKernel\KernelInterface;
use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
use Sensio\Bundle\GeneratorBundle\Generator\BundleGenerator;
use Sensio\Bundle\GeneratorBundle\Command\Helper\DialogHelper;
use Sensio\Bundle\GeneratorBundle\Manipulator\KernelManipulator;
use Sensio\Bundle\GeneratorBundle\Manipulator\RoutingManipulator;

En met een paar witregels erbij is het al helemaal mooi:

use Symfony\Component\Console\Output\Output;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\HttpKernel\KernelInterface;

use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;

use Sensio\Bundle\GeneratorBundle\Generator\BundleGenerator;
use Sensio\Bundle\GeneratorBundle\Command\Helper\DialogHelper;
use Sensio\Bundle\GeneratorBundle\Manipulator\KernelManipulator;
use Sensio\Bundle\GeneratorBundle\Manipulator\RoutingManipulator;

example.php

<?php

namespace Acme;

use Acme\Entity\Foo;
use Acme\Form\Type\LoginForm;

use Foo\Framework\Baz;

class FooBar
{
    const SOME_CONST = 42;

    private $fooBar;

    public function __construct($dummy)
    {
        $this->fooBar = $this->transformText($dummy);
    }

    private function transformText($dummy, $options = array())
    {
        $mergedOptions = array_merge($options, array(
            'some_default' => 'values',
        ));

        if (true === $dummy) {
            return;
        }
        if ('string' === $dummy) {
			$dummy = preg_replace_callback('/foo/', function($matches) {
				return ucwords($matches);
			}, $dummy);
        }

        return $dummy;
    }
}