Een PHP-snippet opschonen

Waarom opmaak de lezer helpt

Mensen scannen code op basis van de vorm. Wanneer accolades netjes uitgelijnd staan en elke instructie een eigen regel heeft, ziet de lezer de structuur voordat hij ook maar één woord leest. Een reviewer ziet dan een ontbrekende accolade of een lus op de verkeerde plek. Een plat blok tekst verbergt dat allemaal.

Voor en na

Origineel, gekopieerd uit een log:

<?php function total($items){$sum=0;foreach($items as $item){$sum+=$item["price"];}return $sum;}

Opgeschoond met 4 spaties:

<?php function total($items)
{
    $sum=0;
    foreach($items as $item)
    {
        $sum+=$item["price"];
    }
    return $sum;
}

Een korte checklist voordat je plaatst

• Verwijder geheimen. De tekst die je hier plakt wordt op onze server verwerkt, gebruik dus geen echte inloggegevens, tokens of klantgegevens.
• Houd het voorbeeld minimaal, met alleen de regels die nodig zijn om het probleem te tonen.
• Vermeld welke PHP-versie je gebruikt en wat je had verwacht.
• Vergelijk de opgemaakte code met het origineel. De tool wijzigt alleen de indeling, maar de regels voor witruimte kunnen opmerkingen en tekenreeksen beïnvloeden.
• Zet het resultaat in een codeblok, zodat de inspringing behouden blijft.

Wat deze tool niet is

Hij vindt geen fouten, voert je code niet uit en controleert geen stijlregels. Een nette indeling maakt een probleem makkelijker te zien, maar lost het niet op.

Waar dit helpt

• Een supportticket of bugrapport met een codevoorbeeld.
• Een vraag op een ontwikkelaarsforum of in een chatkanaal.
• Een documentatiepagina of tutorial waarin een voorbeeld er verzorgd uit moet zien.
• Een reviewopmerking waarin je een wijziging in een deel van een functie voorstelt.

In al deze gevallen ziet de lezer eerst de structuur en daarna het probleem, en dat is de volgorde die je wilt.

Houd de snippet eerlijk

Maak de opmaak van de code die je echt gaat plaatsen, en niet van een netter herschreven versie. Als je variabelenamen inkort of regels weglaat om het voorbeeld te laten passen, draai de ingekorte versie dan eerst zelf. Een strakke snippet die het probleem niet reproduceert, kost de lezer alleen tijd. Als je een opmerking over het verwachte resultaat toevoegt, zet die dan in gewone woorden boven het codeblok.