Nuttig commentaar

Door Koen Vlaswinkel, 1 jaar geleden, 22.378x bekeken

Om je code leesbaar te maken, ook na een paar jaar, moet je je code goed documenteren. Hiervoor zijn allemaal stijlen en ik zal er een paar toelichten:
- De 4 algemene stijlen van PHP, zoals //, # en /*.
- Hoe je gegevens mooi kan laten zien in een tabel
- De algemene stijl van documenteren voor phpDocumenter
- Een paar nuttige tags van phpDocumenter

Bron: PHP Kookboek, Ward van der Put

Gesponsorde koppelingen

Inhoudsopgave

  1. Inleiding
  2. Commentaar in vier stijlen
  3. Tabellen in commentaar
  4. phpDocumenter

 

21 reacties op 'Nuttig commentaar'

PHP hulp
PHP hulp
0 seconden vanaf nu
 

Gesponsorde koppelingen

Obelix en Idefix
Obelix en Idefix
1 jaar geleden
 
2 +1 -0 -1
Bronvermelding lijkt me wel zo netjes, als je iets nagenoeg letterlijk overneemt. In dit geval uit PHP kookboek (inclusief voorbeelden).
Koen Vlaswinkel
Koen Vlaswinkel
1 jaar geleden
 
0 +1 -1 -1
Bron heb ik nu wel vermeld. Het is trouwens niet precies overgenomen, er staan wat veranderingen in en ik heb overbodige delen weggelaten.
Wouter J
Wouter J
1 jaar geleden
 
0 +1 -0 -1
Jammer dat het letterlijk is overgenomen...

Maar toch wat puntjes:
Hoofdstuk 2:
Er bestaat een verschil tussen /* en /** met een extra sterretje. Als je het commentaar opent met /**, dan wordt het overgenomen door phpDocumenter, waarover later meer.

Er bestaat totaal geen verschil tussen /* of /**. Alleen hebben de *Documenters bedacht dat het handig is om onderscheid te maken tussen document comments en gewone multi line comments en toen hebben ze de /** bedacht.

Tevens mis ik dat je in dit hoofdstuk het echte verschil tussen // (en #) en /* */ noemt: single line vs multi line

Hoofdstuk 4
Ik vind het altijd makkelijk om verschillende tags met een spatie van elkaar te scheiden, dat is altijd wel makkelijk. Ook vertel je nergens hoe een PHPdoc comment is opgebouwd:
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
<?php
/**
 * [Short description]
 *
 * [Long description]
 *
 * [Tags]
 */
?>


Ook een return tag kan een description bevatten (al is dat vaak overbodig).

Bij meerdere authors ga je die niet met een komma scheiden, maar gebruik je gewoon meerdere author tags (zoals je ook met param doet)

Merk op dat er veel andere PHP documenters zijn dan PHPdoc, bijv. Sami

[sidenote]
Voor JavaScript kun je YUIdoc gebruiken
[/sidenote]
Koen Vlaswinkel
Koen Vlaswinkel
1 jaar geleden
 
0 +1 -0 -1
Wouter, ik heb jouw suggesties en verbeteringen opgenomen in de tutorial.
Niels Kieviet
Niels Kieviet
1 jaar geleden
 
0 +1 -0 -1
Hoi Koen,

Allereerst een leuke toevoeging.

Even een paar opmerkingen:

Style van schrijven:

Ik vind de intro tekst van je tutorial iets te summier. Kan je deze wat uitbreiden? Bijvoorbeeld gesommeerd weergeven wat je gaat behandelen.

Op dit moment is het vlak gesponsorde koppelingen (wat overigens niet aan jouw ligt) groter dan de intro tekst. Dat is een beetje storend :-)

Algemeen:

- Probeer iets meer te werken met paragrafen. (Zie inleiding. Is één grote lap tekst)
- Wanneer je zegt: Ik ga een paar dingen bespreken, zet dat dan in een opsomming.
- Nawoord vind ik ook te kort. Wanneer dat zo kort is kan je hem beter weglaten denk ik.

Inhoudelijk:

Tot slot, ben ik het niet geheel met je tutorial eens. Huh? Hoezo niet dan? Waarom zeg je hier dan dat je PHPDoc / Documentatie wel altijd moet toevoegen?

Pas geleden las ik dit artikel.
Eerst was ik het hier totaal mee eens. Nu heb ik mijn mening iets aangepast.

Ik ben het dus niet helemaal eens met de stelling:

"So stop making excuses, write the damm comment".

Jason geeft het volgende voorbeeld:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
<?php

$pieces = explode('.', $image_name);
$extension = array_pop($pieces);

?>


Volgens Jason is het niet direct duidelijk wat deze twee regels doen. (Ben ik het mee eens) Wat doet Jason nu? Het plaatst er het volgende commentaar boven:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
<?php

// Get the extension off the image filename
$pieces = explode('.', $image_name);
$extension = array_pop($pieces);

?>


Wat is daar verkeerd aan dan? Waarom ben jij het daar niet eens dan? Hoe kan je anders zien wat deze code doet?

Ansich, niets mis mee, maar ik heb naar mijn mening een betere manier gevonden. Stel, we zetten dit stukje code om naar een functie.

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
<?php

function getFileExtension($filename) {
      $pieces = explode('.', $filename);
      return array_pop($pieces);
}

?>


Is deze code niet veel beter leesbaar? En naast dat, de code is ook nog eens beter in gebruik.

Wanneer dan wel? Gebruik jij dan nooit commentaar?

Ja natuurlijk wel. Stel je hebt een functie die een bepaalde controle uitvoert. Wanneer je die code leest weet je niet precies waarom die controle uitgevoerd wordt. In dit geval is een stukje commentaar wel handig. Dan wordt het namelijk duidelijk waarom die controle wordt uitgevoerd.

De stelregel voor commentaar schrijven is dus niet: beschrijven wat de code doet, maar waarom de code datgene doet.

Niels
Ozzie PHP
Ozzie PHP
1 jaar geleden
 
0 +1 -0 -1
Niels Kieviet:
De stelregel voor commentaar schrijven is dus niet: beschrijven wat de code doet, maar waarom de code datgene doet.

Niels, is dit jouw eigen stelregel? Hoe bedoel je dit precies? Ik schrijf alleen op WAT de code doet.

Voorbeeld:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
<?php

// Return the user's name.
public function getName() {
  return $this->name;
}
?>


Jij zou dan dit doen? :-)))

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
<?php

// Return the user's name because I want to know what his name is.
public function getName() {
  return $this->name;
}
?>
Jeroen vd
jeroen vd
1 jaar geleden
 
0 +1 -0 -1
wat niels al probeerde te zeggen, de functienaam werkt hier al als commentaar. het enige commentaar dat dan nodig zal zijn is verdere informatie. en ja, dat kan waarom zijn.
Ozzie PHP
Ozzie PHP
1 jaar geleden
 
0 +1 -0 -1
@Jeroen, sinds wanneer heet jij Niels? ;-)

De vraag is dus of dat Niels z'n eigen stelregel is. Ik schrijf altijd op WAT een functie doet. Stel je hebt een functie die iets controleert, dan zou ik in het commentaar bijv. zeggen "Controleer of de gebruiker de juiste bevoegdheden heeft.". Echter, als ik de interpretatie van Niels volg, dan zou hij dus het WAAROM beschrijven. Ik vraag me dan af waar ik aan moet denken, zoiets als "Voer deze functie uit om te controleren of de gebruiker de juiste bevoegdheden heeft". Zoiets? Zo ja... wat is dan het daadwerkelijke verschil tussen beide varianten?
Jeroen vd
jeroen vd
1 jaar geleden
 
0 +1 -0 -1
niet. ik kan me alleen goed vinden in niels zn gedachtegang.

als jij een functie schrijft met naam validateString(). zou jij daar nog commentaar bijschrijven? ik niet. hoogstens zoiets als "zorgt ervoor dat je zeker weet dat je met een string te maken het." zoiets. wat de functie doet staat in de naam, het 'waarom' in het commentaar. het is een beetje moeilijk hier een naam aan te geven, maar 'waarom' komt denk ik het beste in de buurt.
Wouter J
Wouter J
1 jaar geleden
 
0 +1 -0 -1
Ik ben het half eens met Niels.

Functies als getters en setters enzo hebben geen commentaar nodig en ook veel functienamen beschrijven goed wat het is. Vaak is het schrijven voor commentaar niet echt nodig.

In elk geval, de regel met de short description. Tags als @return of @param zijn erg handig om erbij te hebben om snel wat info te krijgen over een method.

Tevens gebruik ik bij alles PHPdoc en volledig (bij alle classes/interfaces en methods, niet bij properties). Dit doe ik omdat ik altijd API Documentatie genereer. Dan is het handig om alles gedocumenteerd te hebben.
Kees Schepers
kees Schepers
1 jaar geleden
 
0 +1 -0 -1
Quote:
als jij een functie schrijft met naam validateString(). zou jij daar nog commentaar bijschrijven? ik niet.


Het kan aan mij liggen maar mij zegt 'validateString' mij helemaal niks hoor? Wat valideert het dan? Ik denk eerder aan isStringLowercase() die test of alle karakters lowercase zijn. In zo'n geval ben ik het grotendeels met Niels eens en hoef je alleen de parameters / return waarde te commenten.
Niels Kieviet
Niels Kieviet
1 jaar geleden
 
0 +1 -0 -1
@Ozzie,

Het is een persoonlijk voorkeur, maar ik ben van mening dat commentaar in het meeste gevallen overbodig is. (Lees niet PHPDoc)

Dus ik zet bijvoorbeeld geen commentaar bij de volgende methode:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
<?php

class User {

      public function getById($id) {}
}

?>


Maar stel ik zet in de methode een paar rare controles waar je niet direct van af kunt lezen WAAROM die controles uitgevoerd worden is het tijd voor een stukje commentaar ;-)

Snap je mijn punt?

@WouterJ
Ik bedoel niet de PHPDoc tags, maar echte documentatie ;-) PHPDoc gebruik ik natuurlijk altijd ;-)
Wouter J
Wouter J
1 jaar geleden
 
0 +1 -0 -1
Niels, maar met PHPdoc plaats je toch al comments bij zo´n functie. Dus ik snap niet wat je bedoelt met 'geen commentaar' plaats je bij sommige methods dan en PHPdoc en normale comments?
Ozzie PHP
Ozzie PHP
1 jaar geleden
 
1 +1 -0 -1
thanks voor je toelichting Niels!
Niels Kieviet
Niels Kieviet
1 jaar geleden
 
1 +1 -0 -1
Hoi Wouter,

Wat ik bedoel is dit:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
10
<?php

/**
 * @param    Int    $id
 * @access   Public
 * @return   User
 */
public function getById($id) {}

?>


Ik schrijf dus niet:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
<?php

/**
 * Retourneert aan de hand van een ID een user object.
 * ...
 */

?>


Ik plaats een stukje commentaar boven code in de methode die niet in één oog opslag leesbaar zijn. (Lees: Waarvan niet af te lezen valt waarom die controle gedaan wordt)

Snap je?
Wouter J
Wouter J
1 jaar geleden
 
1 +1 -0 -1
Ahh zo, bedankt. Ik wist niet dat je de short-description ook kon weglaten, is wel zo handig soms...
Johan Rombouts
Johan Rombouts
1 jaar geleden
 
0 +1 -0 -1
Het begint er nu op te lijken dat je zo min mogelijk commentaar moet gebruiken.
Ik maak heel veel gebruik van commentaar. Vind ik wel makkelijk. Hoe meer commentaar hoe liever.
Of zie ik dat verkeerd.
Niels Kieviet
Niels Kieviet
9 maanden geleden
 
0 +1 -0 -1
Hoi Johan,

Het is al 4 maanden geleden dat je het bericht geplaatst hebt, maar ik wil toch nog even op je bericht reageren.

Quote:
Hoe meer commentaar hoe liever. Of zie ik dat verkeerd.


In mijn ogen wel. Je moet alleen commentaar plaatsen wanneer het nodig is. Altijd commentaar heeft totaal geen zin, en kost ook nog eens veel tijd.

Daarbij bedoel ik niet het gebruik van PHPDoc. Ik zet boven een methode altijd PHPDoc. Allereerst voor het genereren van een API en ten tweede voor het gebruik van autocompletion in mijn editor.

Mijn punt is dat je bewust commentaar moet plaatsen en niet boven elke functie commentaar moet plaatsen omdat het kan, leuk is, mooi staat, of omdat je het zo gewend bent ;-)

Niels
Bernhard Flokstra
Bernhard Flokstra
2 maanden geleden
 
0 +1 -0 -1
@Johan,

Het lijkt vaak dat, vooral PHP programmeurs vinden dat commentaar het doel moet zijn. Ze gebruiken heel onduidelijke functie/methode namen en met commentaar proberen ze dan duidelijk te maken wat een functie/methode doet.

Zelf gebruik ik het Clean code principe van Michael Feathers en Robert Martin. Volgens dat principe kun je beter langere maar goed leesbare en duidelijke functie en methode namen gebruiken dan korte en nietszeggende namen.

Als ik een functie schrijf dan houd ik mij aan een aantal punten waardoor commentaar bijna altijd overbodig is:
1. Beschrijvende functienamen. Daardoor zegt de functienaam net zo veel over de code als dat het commentaar doet.
2. Commentaar enkel als het echt echt echt echt nodig is. En dan niet meer dan 1 regel commentaar. Is er meer nodig? Dan is de functienaam niet duidelijk genoeg (uitzonderingen nagelaten uiteraard).
3. Gebruik het 1 taak principe. Een functie moet maar 1 taak hebben, en zo kort mogelijk zijn. Een functie met honderden regels (zoals in de inleiding staat) kan nagenoeg altijd worden refactored. Hoe meer regels hoe onduidelijker de functie is en hoe moeilijker het, zelfs met commentaar, word om over een jaar nog te zien wat de functie doet.

Sinds ik dit principe gebruik heb ik geen commentaar meer gebruikt. Daarnaast laat ik regelmatig mensen mijn classes lezen. Zij kunnen bijna altijd direct zien wat de code doet, zonder echt naar de code te kijken. Als zij het niet uit kunnen vinden wat de code doet dan is er iets mis met mijn functies of functienamen. Niet met het commentaar.

bernhard
Niels Kieviet
Niels Kieviet
2 maanden geleden
 
0 +1 -0 -1
Hallo Bernhard,

Wat doe jij met moeilijk te lezen inline code? Bijvoorbeeld bij een import script?

Niels
PHP hulp
PHP hulp
0 seconden vanaf nu
 

Gesponsorde koppelingen

Bernhard Flokstra
Bernhard Flokstra
2 maanden geleden
 
0 +1 -0 -1
Hoi Niels,

Om te beginnen schrijf ik de code zo leesbaar mogelijk. Alles waar ik een klasse van kan maken maak ik ook een klasse van.

Maar bij bijvoorbeeld een import script ontkom je er soms niet aan om commentaar te plaatsen. En dan plaats ook ik commentaar. Maar zoals ik al zei in mijn vorige bericht, zelden meer dan een regel commentaar. Alleen commentaar die strikt noodzakelijk is.

Groeten,
Bernhard

Om te reageren heb je een account nodig en je moet ingelogd zijn.

Inhoudsopgave

  1. Inleiding
  2. Commentaar in vier stijlen
  3. Tabellen in commentaar
  4. phpDocumenter

Labels

PHP tutorial opties