Tutorials
Netjes programmeren
De volgende tutorial is grotendeels een vertaling en bewerking van de codeerstandaard van PEAR. Het leert je om efficiënt, consistent en consequent te programmeren.
Pagina 1
Inspringen & Regellengte
Je hoort vaak op het PHPhulp forum dat mensen iets meer gebruik moeten maken van de spatiebalk, omdat de geposte code anders niet te lezen is.
Eén van de meest belangrijke punten van netjes programmeren, betreft wel het inspringen; het maakt je code namelijk veel overzichtelijker en vergroot de leesbaarheid. En dat niet alleen voor anderen, maar ook voor jezelf, wanneer je na een jaar, een week of zelfs na een dag je code weer terugziet.
Bewijs zien?
Kijk eerst eens naar dit voorbeeld:
<?php
if($_SESSION[‘login’]=false)
{print ‘Jammer maar helaas’;}
else{
$login=true;
header(‘users/index.php’);
}
?>
Waarschijnlijk duurde het bij de meeste mensen even om dit simpele voorbeeld te ontcijferen. Stel je voor dat dit voorbeeld honderd regels telde, of – nog erger – tientallen pagina’s code wat bij grote projecten vaak het geval zal zijn. Een beetje inspringen zou het al makkelijker moeten maken om in de code te duiken:
<?php
if ($_SESSION[‘login’] = false) {
print ‘jammer, maar helaas’;
} else {
$login = true;
header(‘users/index.php’);
}
?>
De PEAR codeerstandaard schrijft voor dat je met vier spaties per keer inspringt, en niet met tabs (ik vermoed dat platte tekst dat niet aankan?).
Sommige editors kan je echter zo instellen dat een tab gelijk komt te staan aan vier spaties.
In Emacs schijn je dat zo te kunnen doen:
(defun php-mode-hook ()
(setq tab-width 4
c-basic-offset 4
c-hanging-comment-ender-p nil
indent-tabs-mode
(not
(and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
(string-match "\.php$" (buffer-file-name))))))
En in Vim zo:
set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4
Ik heb zelf echter géén ervaring met beide editors, dus ik kan je niet vertellen of dat bovenstaande klopt. Mocht er iemand zijn die wel een dergelijke editor gebruikt, dan hoor ik dat graag.
Het wordt bovendien aangeraden door PEAR om regels code na circa 75-85 karakters af te breken. Dit is echter geen standaard regelgeving en ’t is daarom min of meer aan jezelf om te bepalen hoe je code het meest overzichtelijk blijft.
Eén van de meest belangrijke punten van netjes programmeren, betreft wel het inspringen; het maakt je code namelijk veel overzichtelijker en vergroot de leesbaarheid. En dat niet alleen voor anderen, maar ook voor jezelf, wanneer je na een jaar, een week of zelfs na een dag je code weer terugziet.
Bewijs zien?
Kijk eerst eens naar dit voorbeeld:
<?php
if($_SESSION[‘login’]=false)
{print ‘Jammer maar helaas’;}
else{
$login=true;
header(‘users/index.php’);
}
?>
Waarschijnlijk duurde het bij de meeste mensen even om dit simpele voorbeeld te ontcijferen. Stel je voor dat dit voorbeeld honderd regels telde, of – nog erger – tientallen pagina’s code wat bij grote projecten vaak het geval zal zijn. Een beetje inspringen zou het al makkelijker moeten maken om in de code te duiken:
<?php
if ($_SESSION[‘login’] = false) {
print ‘jammer, maar helaas’;
} else {
$login = true;
header(‘users/index.php’);
}
?>
De PEAR codeerstandaard schrijft voor dat je met vier spaties per keer inspringt, en niet met tabs (ik vermoed dat platte tekst dat niet aankan?).
Sommige editors kan je echter zo instellen dat een tab gelijk komt te staan aan vier spaties.
In Emacs schijn je dat zo te kunnen doen:
(defun php-mode-hook ()
(setq tab-width 4
c-basic-offset 4
c-hanging-comment-ender-p nil
indent-tabs-mode
(not
(and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
(string-match "\.php$" (buffer-file-name))))))
En in Vim zo:
set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4
Ik heb zelf echter géén ervaring met beide editors, dus ik kan je niet vertellen of dat bovenstaande klopt. Mocht er iemand zijn die wel een dergelijke editor gebruikt, dan hoor ik dat graag.
Het wordt bovendien aangeraden door PEAR om regels code na circa 75-85 karakters af te breken. Dit is echter geen standaard regelgeving en ’t is daarom min of meer aan jezelf om te bepalen hoe je code het meest overzichtelijk blijft.
Pagina 2
Naamgeving
Er zijn diverse manieren om je klassen en variabelen zinvolle namen te geven. Ook hier geldt weer, het maakt niet zoveel uit wát je volgt, als je de naamgeving maar consequent volhoudt.
Ik zal eerst de Hungarian Naming Convention (hierna: HNC) bespreken, die ook in het PHP 5 Superboek van Wouter Tengeler wordt beschreven. Daarna de manier waarop PEAR het graag wil zien.
Hungarian Naming Convention
Volgens de HNC is het handig om het type van de geretourneerde variabele op te nemen in de naam, wat je overigens alleen bij variabelen doet aangezien een functie meerdere typen kan retourneren.
De naam van een variabele bouw je als volgt op:
Allereerst kijk je naar het bereik wat de variabele heeft of zou moeten hebben. Is deze beschikbaar binnen een klasse of wordt hij doorgegeven als parameter? Wellicht is het een globale variabele?
Mogelijke waarden voor de scope (het bereik) van de variabelen zijn g, m, l en p:
g: global. Een variabele die overal kan worden gebruikt.
m: member. Een variabele die alléén binnen een klasse kan worden gebruikt. Deze declareer je in het algemeen voor het aanroepen van de constructor en zijn te herkennen aan $this->variabele.
l: local. Dit is een lokale variabele, die binnen een functie voor het eerst een waarde heeft gekregen.
p: parameter. Een parameter wordt aan een functie of methode (functie binnen een klasse) meegegeven en kan alleen in die functie gebruikt worden. Parameters zijn de variabelen die tussen de haakjes komen na een functieaanroep, bijvoorbeeld:
function functie($p_sParameter1, $p_iParameter2 = 100) {}
Ondanks het feit dat (of juist omdat) het voor PHP niet uitmaakt wat voor type een variabele krijgt (in de programmeertaal C++ bijvoorbeeld, geef je eerst aan dat een variabele een integer is met int), is het handig bij het debuggen om aan te geven wat voor type variabele een string zou moeten zijn. Nadat je de scope van de variabele hebt aangeduid, voeg je daarom een liggend streepje (underscore) toe, waarna je in kleine letters het type van de variabele beschrijft. Het is gebruikelijk hiervoor afkortingen te gebruiken.
Een i geeft bijvoorbeeld aan dat het om een integer gaat, een s geeft aan dat de variabele een string bevat. Onderstaande lijst is algemeen geaccepteerd, maar je kunt natuurlijk altijd zelf bepalen wat je gebruikt. Let er dan wel op dat je dat consequent en consistent doet!
numeriek n
-- float f
-- integer i
-- long l
string s
boolean b
array a
datum d
object o of obj
function fn
referentie r
variant v
constante c
Voor de meesten zal bovenstaande lijst voldoende zijn. Soms is het echter wenselijk dat je een object nader specificeerd (zoals je ook de numerieke waarde verder kunt specificeren in float, integer of long), Google dan even op "Hungarian Naming Convention" en je object, bv.: 'Document', 'Recordset' of 'Form'.
Nadat je het type variabele hebt aangeduid, geef je een beschijvende naam voor de varabele, beginnend met een hoofdletter bij ieder ‘woord’ van de naam. Bijvoorbeeld: Title, HeaderHeight of CountValue.
m_fCountValue // een variabele binnen een klasse die een float bevat
g_sTitle // een globale variabele die een string bevat
p_iHeaderHeight // een parameter die een integer waarde bevat
Wanneer je naar bovenstaande variabelen kijkt, krijg je al een aardig idee over wat de variabele bevat en hoe deze gebruikt wordt in een programma.
De PEAR methode
De PEAR standaard schrijft ons voor dat klassen altijd een beschrijvende naam moeten hebben, waarbij de naam van de klasse met een hoofdletter begint. Voorbeelden van klassenamen volgens de PEAR standaard:
Log
Net_Finger
HTML_Upload_Error
Een functie of methode zou de pakketnaam als prefix moeten krijgen, om te voorkomen dat functies uit verschillende pakketten conflicteren. De eerste letter van de naam (na de prefix) is een kleine letter. Iedere volgende letter van een nieuw “woord” krijgt een hoofdletter. Deze stijl wordt ook wel aangehaald als “bumpy case” of “camel caps”:
connect()
getData()
buildSomeWidget()
XML_RPC_serializeData()
Members van klassen die private zijn, worden voorafgegaan door een liggende streep:
_sort()
_initTree()
$this->_status
Protected members gaan daarentegen niet vooraf door een liggende streep.
protected $somevar
protected function initTree()
Constanten moeten altijd volledig in hoofdletters geschreven worden, met liggende strepen om woorden te scheiden. Constante namen die in klassen/pakketten worden gebruikt, worden in hoofdletters geschreven met de naam van de klasse/pakket als prefix. Bijvoorbeeld: de constanten die gebruikt worden door het DB:: pakket beginnen allemaal met DB_.
Opmerking: de constanten true, false en null zijn uitgezonderd van de regel dat constanten in hoofdletters worden geschreven; deze worden altijd in kleine letters geschreven.
Als je pakket globale variabelen gebruikt, dan moeten de namen ervan beginnen met een enkel liggend streepje gevolgd door de pakketnaam en wederom een liggend streepje. Het PEAR pakket bijvoorbeeld gebruikt een globale variabele die $_PEAR_destructor_object_list heet.
Ik zal eerst de Hungarian Naming Convention (hierna: HNC) bespreken, die ook in het PHP 5 Superboek van Wouter Tengeler wordt beschreven. Daarna de manier waarop PEAR het graag wil zien.
Hungarian Naming Convention
Volgens de HNC is het handig om het type van de geretourneerde variabele op te nemen in de naam, wat je overigens alleen bij variabelen doet aangezien een functie meerdere typen kan retourneren.
De naam van een variabele bouw je als volgt op:
Allereerst kijk je naar het bereik wat de variabele heeft of zou moeten hebben. Is deze beschikbaar binnen een klasse of wordt hij doorgegeven als parameter? Wellicht is het een globale variabele?
Mogelijke waarden voor de scope (het bereik) van de variabelen zijn g, m, l en p:
g: global. Een variabele die overal kan worden gebruikt.
m: member. Een variabele die alléén binnen een klasse kan worden gebruikt. Deze declareer je in het algemeen voor het aanroepen van de constructor en zijn te herkennen aan $this->variabele.
l: local. Dit is een lokale variabele, die binnen een functie voor het eerst een waarde heeft gekregen.
p: parameter. Een parameter wordt aan een functie of methode (functie binnen een klasse) meegegeven en kan alleen in die functie gebruikt worden. Parameters zijn de variabelen die tussen de haakjes komen na een functieaanroep, bijvoorbeeld:
function functie($p_sParameter1, $p_iParameter2 = 100) {}
Ondanks het feit dat (of juist omdat) het voor PHP niet uitmaakt wat voor type een variabele krijgt (in de programmeertaal C++ bijvoorbeeld, geef je eerst aan dat een variabele een integer is met int), is het handig bij het debuggen om aan te geven wat voor type variabele een string zou moeten zijn. Nadat je de scope van de variabele hebt aangeduid, voeg je daarom een liggend streepje (underscore) toe, waarna je in kleine letters het type van de variabele beschrijft. Het is gebruikelijk hiervoor afkortingen te gebruiken.
Een i geeft bijvoorbeeld aan dat het om een integer gaat, een s geeft aan dat de variabele een string bevat. Onderstaande lijst is algemeen geaccepteerd, maar je kunt natuurlijk altijd zelf bepalen wat je gebruikt. Let er dan wel op dat je dat consequent en consistent doet!
numeriek n
-- float f
-- integer i
-- long l
string s
boolean b
array a
datum d
object o of obj
function fn
referentie r
variant v
constante c
Voor de meesten zal bovenstaande lijst voldoende zijn. Soms is het echter wenselijk dat je een object nader specificeerd (zoals je ook de numerieke waarde verder kunt specificeren in float, integer of long), Google dan even op "Hungarian Naming Convention" en je object, bv.: 'Document', 'Recordset' of 'Form'.
Nadat je het type variabele hebt aangeduid, geef je een beschijvende naam voor de varabele, beginnend met een hoofdletter bij ieder ‘woord’ van de naam. Bijvoorbeeld: Title, HeaderHeight of CountValue.
m_fCountValue // een variabele binnen een klasse die een float bevat
g_sTitle // een globale variabele die een string bevat
p_iHeaderHeight // een parameter die een integer waarde bevat
Wanneer je naar bovenstaande variabelen kijkt, krijg je al een aardig idee over wat de variabele bevat en hoe deze gebruikt wordt in een programma.
De PEAR methode
De PEAR standaard schrijft ons voor dat klassen altijd een beschrijvende naam moeten hebben, waarbij de naam van de klasse met een hoofdletter begint. Voorbeelden van klassenamen volgens de PEAR standaard:
Log
Net_Finger
HTML_Upload_Error
Een functie of methode zou de pakketnaam als prefix moeten krijgen, om te voorkomen dat functies uit verschillende pakketten conflicteren. De eerste letter van de naam (na de prefix) is een kleine letter. Iedere volgende letter van een nieuw “woord” krijgt een hoofdletter. Deze stijl wordt ook wel aangehaald als “bumpy case” of “camel caps”:
connect()
getData()
buildSomeWidget()
XML_RPC_serializeData()
Members van klassen die private zijn, worden voorafgegaan door een liggende streep:
_sort()
_initTree()
$this->_status
Protected members gaan daarentegen niet vooraf door een liggende streep.
protected $somevar
protected function initTree()
Constanten moeten altijd volledig in hoofdletters geschreven worden, met liggende strepen om woorden te scheiden. Constante namen die in klassen/pakketten worden gebruikt, worden in hoofdletters geschreven met de naam van de klasse/pakket als prefix. Bijvoorbeeld: de constanten die gebruikt worden door het DB:: pakket beginnen allemaal met DB_.
Opmerking: de constanten true, false en null zijn uitgezonderd van de regel dat constanten in hoofdletters worden geschreven; deze worden altijd in kleine letters geschreven.
Als je pakket globale variabelen gebruikt, dan moeten de namen ervan beginnen met een enkel liggend streepje gevolgd door de pakketnaam en wederom een liggend streepje. Het PEAR pakket bijvoorbeeld gebruikt een globale variabele die $_PEAR_destructor_object_list heet.
Pagina 3
Overig
Bestanden invoegen
Wanneer je onvoorwaardelijk een klasse invoegt, gebruik je require_once. Wanneer je dit wel met voorwaarden doet (in meer geavanceerdere toepassingen), gebruik je include_once. Ze zullen er beide voor zorgen dat de klasse slechts eenmaal ingevoegd worden.
Overigens maken zowel require_once als include_once gebruik van dezelfde bestandslijst, dus je hoeft niet bang te zijn dat een bestand meerdere keren ingevoegd wordt. Met andere woorden: een bestand dat is ingevoegd met require_once zal niet nogmaals worden ingevoegd door include_once.
Opmerking: include_once en require_once zijn statements, en geen functies. Je moet daarom geen haakjes gebruiken rond de bestandsnaam!
PHP code tags
Gebruik altijd <?php ?> om PHP code in te sluiten; nooit de korte notatie <? ?>. Niet alleen is dit vereist voor PEAR compatibiliteit, het is ook de meest handzame manier om PHP code in te voegen op diverse besturingssystemen. Op deze wijze voorkom je bovendien verwarring met andere talen als XML, die – in plaats van <?xml ?> ook de korte notatie <? ?> toestaan.
Bestandsformatting
Bestanden sla je op in ASCII formaat en gebruiken ISO-8859-1 character encoding. Ze moeten eveneens “UNIX formatted” worden, maar ook hier geldt dat de meeste mensen daar niet zoveel rekening mee hoeven te houden. UNIX formatted houdt overigens in dat regels alleen mogen eindigen met een line-feed (LF), en niet met een carriage return (CR; Macintosh) of carriage return/line feed combinatie (CRLF; Windows). Bovendien moet je nog één line-feed plaatsen na de afsluitende tag (?>), zodat de cursor zich één regel onder de afsluitende tag zou moeten bevinden.
Wanneer je onvoorwaardelijk een klasse invoegt, gebruik je require_once. Wanneer je dit wel met voorwaarden doet (in meer geavanceerdere toepassingen), gebruik je include_once. Ze zullen er beide voor zorgen dat de klasse slechts eenmaal ingevoegd worden.
Overigens maken zowel require_once als include_once gebruik van dezelfde bestandslijst, dus je hoeft niet bang te zijn dat een bestand meerdere keren ingevoegd wordt. Met andere woorden: een bestand dat is ingevoegd met require_once zal niet nogmaals worden ingevoegd door include_once.
Opmerking: include_once en require_once zijn statements, en geen functies. Je moet daarom geen haakjes gebruiken rond de bestandsnaam!
PHP code tags
Gebruik altijd <?php ?> om PHP code in te sluiten; nooit de korte notatie <? ?>. Niet alleen is dit vereist voor PEAR compatibiliteit, het is ook de meest handzame manier om PHP code in te voegen op diverse besturingssystemen. Op deze wijze voorkom je bovendien verwarring met andere talen als XML, die – in plaats van <?xml ?> ook de korte notatie <? ?> toestaan.
Bestandsformatting
Bestanden sla je op in ASCII formaat en gebruiken ISO-8859-1 character encoding. Ze moeten eveneens “UNIX formatted” worden, maar ook hier geldt dat de meeste mensen daar niet zoveel rekening mee hoeven te houden. UNIX formatted houdt overigens in dat regels alleen mogen eindigen met een line-feed (LF), en niet met een carriage return (CR; Macintosh) of carriage return/line feed combinatie (CRLF; Windows). Bovendien moet je nog één line-feed plaatsen na de afsluitende tag (?>), zodat de cursor zich één regel onder de afsluitende tag zou moeten bevinden.
Pagina 4
Controlestructuren
Controlestructuren zijn situaties waarin een evaluatie plaatsvindt, ofwel alle if’s, for’s, while’s, switch’es etcetera. Zoals je wel zult weten, volgt er altijd een openend haakje op het sleutelwoord waardoor het op een functie lijkt.
Om nu een controlestructuur te onderscheiden van een functie, plaats je één spatie tussen het sleutelwoord en het openende haakje. Hieronder een voorbeeld om dat iets te verhelderen. Let ook op het het gebruik van spaties binnen de expressie (dus tussen de twee haakjes) en de plaats van de accolades.
<?php
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
?>
Indien de situatie dat toelaat, zou je ook altijd accolades moeten gebruiken. Dat verhoogt niet alleen de leesbaarheid, maar vermindert ook de kans op fouten wanneer je de code besluit te wijzigen.
Om nu een controlestructuur te onderscheiden van een functie, plaats je één spatie tussen het sleutelwoord en het openende haakje. Hieronder een voorbeeld om dat iets te verhelderen. Let ook op het het gebruik van spaties binnen de expressie (dus tussen de twee haakjes) en de plaats van de accolades.
<?php
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
?>
Indien de situatie dat toelaat, zou je ook altijd accolades moeten gebruiken. Dat verhoogt niet alleen de leesbaarheid, maar vermindert ook de kans op fouten wanneer je de code besluit te wijzigen.
Pagina 5
Een voorbeeld en verder lezen
Omwille van de ruimte en leesbaarheid, verwijs ik je voor een uitgebreid voorbeeld naar http://pear.php.net/manual/en/standards.sample.php.
In deze tutorial heb ik geprobeerd om je wat meer houvast te bieden bij het programmeren, omdat ik daar zelf ook nogal problemen mee had. Uiteraard hoef je niet deze standaard te volgen, maar kan je ook je eigen stijl aanmeten. Wil je je broncode openbaar maken of er samen met anderen aan werken, dan kan het wel handig zijn om een dergelijke standaard te hanteren zodat iedereen op dezelfde manier programmeert.
Ik moet toegeven dat ik zelf ook niet volledig de PEAR coding standards volg; voor naamgeving gebruik ik de HNC, en de headers (in deze tutorial niet besproken) laat ik meestal ook weg. Persoonlijk vind ik dat niet zo erg.
Het gedeelte van de HNC kwam overigens uit het PHP 5 superboek van Wouter Tengeler. De rest was een in meer of mindere mate vrije vertaling van de PEAR coding standards, te vinden op http://pear.php.net/manual/en/standards.php.
Wanneer je op Google zoekt op “PHP coding standards” (voor andere programmeertalen alleen op “coding standards”), vindt je een hoeveelheid aan links die allemaal een eigen standaard hanteren of gebaseerd zijn op een andere standaard (vaak afgeleid van een andere taal).
Het begrip “standaard” is dus nog relatief ;)
Ik ontvang overigens graag reacties en aanvullingen op deze tutorial!
In deze tutorial heb ik geprobeerd om je wat meer houvast te bieden bij het programmeren, omdat ik daar zelf ook nogal problemen mee had. Uiteraard hoef je niet deze standaard te volgen, maar kan je ook je eigen stijl aanmeten. Wil je je broncode openbaar maken of er samen met anderen aan werken, dan kan het wel handig zijn om een dergelijke standaard te hanteren zodat iedereen op dezelfde manier programmeert.
Ik moet toegeven dat ik zelf ook niet volledig de PEAR coding standards volg; voor naamgeving gebruik ik de HNC, en de headers (in deze tutorial niet besproken) laat ik meestal ook weg. Persoonlijk vind ik dat niet zo erg.
Het gedeelte van de HNC kwam overigens uit het PHP 5 superboek van Wouter Tengeler. De rest was een in meer of mindere mate vrije vertaling van de PEAR coding standards, te vinden op http://pear.php.net/manual/en/standards.php.
Wanneer je op Google zoekt op “PHP coding standards” (voor andere programmeertalen alleen op “coding standards”), vindt je een hoeveelheid aan links die allemaal een eigen standaard hanteren of gebaseerd zijn op een andere standaard (vaak afgeleid van een andere taal).
Het begrip “standaard” is dus nog relatief ;)
Ik ontvang overigens graag reacties en aanvullingen op deze tutorial!
Pagina 6
Functies
Functies roep je aan zonder spaties tussen de functienaam en het eerst haakje, en tussen het eerste haakje en de eerste parameter. Net als in de gewone schrijftaal, plaats je wél een spatie tussen de komma en iedere volgende parameter. Vervolgens plaats je weer géén spaties tussen de laatste parameter en het afsluitende haakje en tussen het afsluitende haakje en de puntkomma (maar weer wél tussen een afsluitend haakje en een accolade, zie de vorige pagina).
<?php
$var = foo($bar, $baz, $quux);
?>
Zoals je kunt zien, plaats je ook spaties rond het isgelijkteken. Doe je meer functieaanroepen achter elkaar (of de toewijzing van een variabele), dan kun je meerdere spaties toevoegen om de leesbaarheid te vergroten:
<?php
$short = foo($bar);
$long_variable = foo($baz);
?>
Bevat de functieaanroep parameters met standaardwaarden, dan plaats je deze aan het einde van de lijst (ik meen me te herinneren dat PHP je daartoe zelfs verplichte, anders was het C++). Probeer ook altijd een zinvolle waarde te retourneren uit een functie:
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
?>
De accolades plaats je bij functies op een nieuwe regel. Het werken met en plaatsen van de accolades wordt de ‘one true brace’ methode genoemd, alhoewel het verschillende namen kent (K&R stijl, 1TBS, TOOBTS). Deze methode stamt af uit de programmeertaal C en de brondcode van zowel de UNIX als de Linux kernel is op deze wijze geschreven.
Er zijn overigens ook andere stijlen die je kunt aanhouden, kijk bijvoorbeeld eens hier. Wat je gebruikt maakt op zich niet zoveel uit, als je maar consequent blijft.
<?php
$var = foo($bar, $baz, $quux);
?>
Zoals je kunt zien, plaats je ook spaties rond het isgelijkteken. Doe je meer functieaanroepen achter elkaar (of de toewijzing van een variabele), dan kun je meerdere spaties toevoegen om de leesbaarheid te vergroten:
<?php
$short = foo($bar);
$long_variable = foo($baz);
?>
Bevat de functieaanroep parameters met standaardwaarden, dan plaats je deze aan het einde van de lijst (ik meen me te herinneren dat PHP je daartoe zelfs verplichte, anders was het C++). Probeer ook altijd een zinvolle waarde te retourneren uit een functie:
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
?>
De accolades plaats je bij functies op een nieuwe regel. Het werken met en plaatsen van de accolades wordt de ‘one true brace’ methode genoemd, alhoewel het verschillende namen kent (K&R stijl, 1TBS, TOOBTS). Deze methode stamt af uit de programmeertaal C en de brondcode van zowel de UNIX als de Linux kernel is op deze wijze geschreven.
Er zijn overigens ook andere stijlen die je kunt aanhouden, kijk bijvoorbeeld eens hier. Wat je gebruikt maakt op zich niet zoveel uit, als je maar consequent blijft.
Pagina 7
Commentaar
Vraag een programmeur wat het belangrijkste is aan een omvangrijk project, en menigeen zal antwoorden dat dat het commentaar is. Dat licht toe wat je code doet, hoe het werkt en waarom je het op die manier doet. Uit PEAR pakketten worden commentaarblokken zelfs uit de code geabstraheerd en vrijwel automatisch tot aparte documentatie verheven.
Het is echter moeilijk om het commentaar correct te doseren; niet alleen kan je te weinig commentaar hebben, ook teveel commentaar komt de leesbaarheid (en bestandsgrootte) niet ten goede:
<?php
// if condition matches, go to some page
if ($condition == true) {
header(‘somepage.php’); // redirecting user
// if condition doesn’t match, print an error to the screen.
} else {
print ‘error’; // printing error
} // closing else
?>
In bovenstaand voorbeeld is eigenlijk in het geheel geen commentaar nodig. Voor iedereen zal duidelijk zijn wat bedoelt wordt met een if-else statement. Voor ingewikkeldere of grotere stukken code kan het wel verhelderend zijn om aan te duiden om welke variabele het gaat of wat het doet.
Wanneer moet je commentaar plaatsen? Dat is een beetje natte vingerwerk, maar je kunt het volgende aanhouden: wanneer je naar een stuk code kijkt en denkt “Potjandorie, ik ga niet proberen om te beschrijven wat dat doet!”, heb je commentaar nodig. Voeg dat commentaar in terwijl je typt of vlak erna, voordat je vergeet hoe je code in elkaar steekt.
De globale en soms meer gedetailleerde beschrijving van een bestand of klasse plaats je overigens bovenaan het bestand, in zogenaamde docblocks. Het gebruik van die docblocks ga ik niet verder uitleggen, gezien weinigen hier ook daadwerkelijk hun code aan PEAR ter beschikking zullen stellen. Mocht je dat wel doen, dan verwijs ik je naar de Engelse tekst van de codeerstandaard.
Commentaar in de stijl van C (/* */) en standaard C++ commentaar (//) is overigens allebei prima. Het gebruik van de Perl/shell commentaarstijl (#) wordt daarentegen afgeraden.
Het is echter moeilijk om het commentaar correct te doseren; niet alleen kan je te weinig commentaar hebben, ook teveel commentaar komt de leesbaarheid (en bestandsgrootte) niet ten goede:
<?php
// if condition matches, go to some page
if ($condition == true) {
header(‘somepage.php’); // redirecting user
// if condition doesn’t match, print an error to the screen.
} else {
print ‘error’; // printing error
} // closing else
?>
In bovenstaand voorbeeld is eigenlijk in het geheel geen commentaar nodig. Voor iedereen zal duidelijk zijn wat bedoelt wordt met een if-else statement. Voor ingewikkeldere of grotere stukken code kan het wel verhelderend zijn om aan te duiden om welke variabele het gaat of wat het doet.
Wanneer moet je commentaar plaatsen? Dat is een beetje natte vingerwerk, maar je kunt het volgende aanhouden: wanneer je naar een stuk code kijkt en denkt “Potjandorie, ik ga niet proberen om te beschrijven wat dat doet!”, heb je commentaar nodig. Voeg dat commentaar in terwijl je typt of vlak erna, voordat je vergeet hoe je code in elkaar steekt.
De globale en soms meer gedetailleerde beschrijving van een bestand of klasse plaats je overigens bovenaan het bestand, in zogenaamde docblocks. Het gebruik van die docblocks ga ik niet verder uitleggen, gezien weinigen hier ook daadwerkelijk hun code aan PEAR ter beschikking zullen stellen. Mocht je dat wel doen, dan verwijs ik je naar de Engelse tekst van de codeerstandaard.
Commentaar in de stijl van C (/* */) en standaard C++ commentaar (//) is overigens allebei prima. Het gebruik van de Perl/shell commentaarstijl (#) wordt daarentegen afgeraden.
Reacties
0