Nuttig commentaar

Om verschillende redenen moet je eigenlijk commentaar toevoegen aan je PHP scripts. Het is niet alleen voor iemand anders die misschien in je code kijkt, maar je hebt er zelf ook veel aan. Weet jij bijvoorbeeld nog wat een functie die je een paar jaar geleden hebt gescript doet? Als die functie nu honderden regels code lang is, moet je de hele functie gaan doorzoeken. Daarom is het dus nuttig om je functies van goed commentaar te voorzien.

Het is ook nuttig als je nu of later in teamverband gaat werken. Dan weet iedereen wat de functie doet.

Ik ga een paar dingen bespreken over commentaar. Bijvoorbeeld welke stijlen je kan gebruiken in PHP, hoe je informatie makkelijk kan laten zien en een veel gebruikte stijl om niet in een chaos verdwaald te raken, PHPDocumenter.

In PHP-scripts kun je commentaar toevoegen in verschillende stijlen. Voor één regel commentaar kan je het hekje (#) of dubbel slash (//) gebruiken. Deze stijlen zijn niet van PHP zelf. Ze komen uit andere computertalen, zo komt // uit C++ en # uit Perl. Deze twee zijn single-line, dus één regel. Het is gebruikelijk commentaar toe te voegen boven de regel waarop stukje code wordt uitgevoerd, bijvoorbeeld:

<?php
// Btw-bedrag berekenen met 19%
$btw_bedrag = 0.19 * $bedrag;
// Btw-bedrag afronden op 2 decimalen
$btw_bedrag = round($btw_bedrag, 2);
// Totaal inclusief btw berekenen
$bedrag = $bedrag + $btw_bedrag;
?>

De PHP-parser negeert whitespace. Voor commentaar geldt een uitzondering. Alles vanaf // of # wordt tot het einde van de regel wordt behandeld als commentaar. Als commentaar kort is, wordt het meestal toegevoegd aan het einde van de regel, bijvoorbeeld:

<?php
$btw_bedrag = 0.19 * $bedrag //; 19% btw (omzetbelasting)
$btw_bedrag = round($btw_bedrag, 2); // Btw afronden op centen
$bedrag = $bedrag + $btw_bedrag;
?>

Wil je langere blokken commentaar maken, dan is het mogelijk om ze binnen /* ... */ te zetten in de stijl van C en CSS. Als je dat doet, worden regeleinden wel genegeerd en moet je het commentaar met */ afsluiten. Dit heet dan ook multi-line, omdat het op meerdere regels kan staan. Dit kan duidelijker zijn. Als je bijvoorbeeld bovenstaande code met deze stijl doet, kan je het zo doen:

<?php
/* Het btw-bedrag berekenen met 19% btw, het btw-bedrag afronden op centen en tot slot het hele bedrag berekenen */
$btw_bedrag = 0.19 * $bedrag;
$btw_bedrag = round($btw_bedrag, 2);
$bedrag = $bedrag + $btw_bedrag;
?>

Er bestaat geen verschil tussen /* en /** met een extra sterretje. Maar als je het commentaar opent met /**, dan wordt het wel overgenomen door phpDocumenter, waarover later meer.

Sommige gegevens zijn het beste leesbaar in tabelvorm. Het onderstaande commentaar is een goed voorbeeld daarvan. Voor de meeste webdevelopers is het meteen duidelijk zonder lezen van meerde alinea's. Hier wordt een webformulier verwerkt met PHP en daarna opgeslagen in MySQL.

<?php

/**
 * Nieuw gebruikersaccount openen
 * 
 * +------------------------+------------------+--------------------------+
 * | Formulier in HTML      | Variabele in PHP | Tabel en kolom in MySQL  |
 * +------------------------+------------------+--------------------------+
 * | name="gebruikersnaam"  | $gebruikersnaam  | klanten.gebruikersnaam   |
 * | name="wachtwoord"      | $wachtwoord      | klanten.wachtwoord       |
 * | name="voornaam"        | $voornaam        | klanten.voornaam         |
 * | name="achternaam"      | $achternaam      | klanten.achternaam       |
 * +------------------------+------------------+--------------------------+
 */
?>

Voor commentaar in PHP-scripts gelden nauwelijks regels en niemand doet het hetzelfde. Dit kan tot een chaotische documentatie leiden.

Voor die reden hebben we phpDocumenter (http://phpdoc.org/), om nuttige documentatie te genereren.
phpDocumenter heeft nuttige tags waarmee je allemaal dingen kunt aangeven, zoals input en output. Ik ga nu alleen die tags behandelen, die ook handig zijn als je phpDocumenter niet gebruikt om documentatie aan te maken. Ik kan ze natuurlijk niet allemaal behandelen, dus kijk op http://www.phpdoc.org/docs/latest/index.html als je ze allemaal wilt weten.

Algemeen
Een normaal phpDocumenter document is opgebouwd als volgt:

<?php
/**
 * [Short description]
 *
 * [Long description]
 *
 * [Tags]
 */
?>

Versiebeheer
Bij grotere projecten volgen verschillende versies elkaar snel op. Met de tag @version kan je een versienummer aangeven.

@version 2

Elke versie verschilt van andere versies. Daarvoor zijn het immers verschillende versies... Voor het markeren van onderdelen die nieuw zijn, gebruik je de tag @since gevolgd door een versienummer.

@since 1.2

Zijn bepaalde onderdelen verouderd, dan markeer je die met @deprecated. Hiermee geef je aan dat een onderdeel beter niet meer kan worden gebruikt of dat het in een nieuwe versie zal worden verwijderd. Achter de tag noem je een versienummer en/of geef je een toelichting.

@deprecated 5.3.0

Auteur
Met de tag @author geef je aan wie een PHP-script heeft geschreven.

@author Koen V.

Het is gebruikelijk om hieraan een e-mailadres toe te voegen, zodat als er vragen zijn de auteur makkelijk te bereiken is.

@author Koen V. <[email protected]>

Als je in een team werkt, of er zijn meerdere auteurs, dan gebruik je meerdere keren de tag @author.

@author Koen V. <[email protected]>
@author Piet Pietersen <[email protected]>

Licentie
Als er een licentie op je script zit, kan je de tag @license gebruiken. Je kan daarin verwijzen naar URL, naam en, als er meerdere versies zijn, de versie.

@license http://www.php.net/license/3_01.txt PHP License v3.01

Invoer en uitvoer
Nu komen de belangrijkste tags. De resultaten voor in- en output. Voor de input, datgene dat je tussen de haakjes zet, gebruik je @param. Achter deze tag zet je achtereenvolgens het datatype, de naam en een eventuele toelichting. Voor de return gebruik je @return met daarachter een datatype en eventueel een beschrijving. Zijn er meerdere datatypes mogelijk? Dan scheid je ze door een pipeline (|).

/**
 * Bedrag in euronotatie
 *
 * @param float $bedrag getal dat moet worden weergegeven
 * @param integer $decimalen aantal decimalen, niet vereist
 * @return string Het bedrag in euro's.
 */
function get_bedrag_in_euro($bedrag, $decimalen = 2)
{
    $bedarg = number_format($bedrag, $decimalen, ',', '.');
    $bedrag = '€ ' . $bedrag;
    return $bedrag;
}

Je kan de parameters het beste noemen in de volgorde waarin ze moeten worden doorgegeven.

Hyperlinks
Zelf documentatie schrijven heeft niet zoveel zin als die er al is. Daarom kan je met @link links opnemen naar webpagina's.

<?php
/**
 * Databaseconnecter
 * 
 * Deze klasse is voor het afhandelen van MySQL-databaseverbindingen.
 * 
 * @link http://dev.mysql.com/doc/refman/5.0/en/apis-php-mysqli.html
 * @link http://www.php.net/manual/en/class.mysqli.php
 * @link http://www.phpnet/manual/en/mysql.connect.php
 */
class databaseconnector extends mysqli
{
    
}
?>

Aan het einde van je zware dag
Als een PHP-script nog niet helemaal af is, dan heb je wel iets anders te doen dan documentatie schrijven. Dan is er toch één onmisbare tag: @todo. Met @todo kun je bijhouden wat er nog gedaan moet worden. Je kan ook meerdere @todo tags toevoegen.

<?php
/**
 * E-mailadres valideren
 * 
 * @todo E-mailadressen van meer dan 256 karakters verbieden.
 * @todo Lokale namen van meer dan 64 karakters in e-mailadressen verbieden
 * 
 * @param string $emailadres
 * @return boolean 
 */
function checkemail($email)
{
    
}
?>

Onthoud bij alles dat als je de /** inkort tot /* (met één sterretje) dat het commentaar in phpDocumenter verborgen blijft.

Andere parsers
Ik heb nu alleen maar phpDocumenter behandelt, maar er bestaan ook andere documentatie parsers, zoals Sami(https://github.com/fabpot/Sami).