PHPhulp.nl PHPhulp.nl
35k+ leden Over PHPhulp Offerte opdracht Contact

commentaar... hoe ver ga je?

Door Ozzie PHP op 21-10-2013 17:16 gewijzigd op 21-10-2013 17:17
1.712 views
Ola,

Ik ben benieuwd hoe ver jullie gaan met het becommentarieren van functies/method.

Normaal zou ik bijvoorbeeld dit doen:

<?php

// Add new paths to the existing paths.
public function addPaths($new_paths) {
$prefix_path = $this->prefix_path;
foreach ($new_paths as &$path) $path = $prefix_path . $path;
unset($path);
$this->paths = array_merge($this->paths, $new_paths);
}

?>
Nu was ik eens aan het experimenteren om binnen de method zelf ook commentaar te gebruiken. Dan krijg je dit:

<?php

// Add new paths to the existing paths.
public function addPaths($new_paths) {
// Set the prefix path.
$prefix_path = $this->prefix_path;

// Prefix each path with the prefix path.
foreach ($new_paths as &$path) $path = $prefix_path . $path;
unset($path);

// Merge the existing paths with the new ones.
$this->paths = array_merge($this->paths, $new_paths);
}

?>
Bij deze laatste variant kun je wel heel snel zien wat er in de method gebeurt, maar is het niet een beetje "overkill" vraag ik me af? Ik ben benieuwd hoe jullie hier tegenaan kijken.
Willem vp
22-10-2013 21:35
Sommige mensen houden ook van diepzinnige commentaren. Zoals in dit codefragment uit de source van de vi-editor (ergens uit de jaren '70):

/*
 *      people making love
 *      never exactly the same
 *      just like a snowflake
 */

void
Ignore(int a)
{

        a = a;
}

Maar om nu te zeggen dat ik er wijzer van ben geworden...
Ozzie PHP
22-10-2013 21:39
Hehehe... een ignore functie :)
En dan een wazige tekst erboven. In denk dat de schrijver ervan onder invloed was!
Donny Wie weet
23-10-2013 15:00
Maar stel je werkt met een team aan een project, en je commentaart niet, kan dat ook verwarring ontstaan...

Of iemand die PHP aan het leren is, en jouw mooie scriptje ziet, die weet niet alles wat er gebeurt.

Ik kan bijvoorbeeld wel OOP in hele grote lijnen lezen (niet schrijven :S), en als ik vastloop op een stukje is commentaar altijd verhelderend.
Ozzie PHP
23-10-2013 15:04
Donny, klopt... maar de vraag was tot hoever je moet gaan. Niemand zegt hier dat je helemaal geen commentaar moet gebruiken.

Boven iedere functie/method schrijf ik commentaar (meestal maar 1 regel). Mijn vraag was of je in de functie/method zelf ook nog moet gaan uitleggen wat de code doet. Van de ene kant is dat wel mooi, maar van de andere kant is het ook "overkill", te veel van het goede zeg maar. De commentaar-regel die boven de functie/method staat die moet duidelijk maken wat die functie/method doet. En dat is eigenlijk alles wat jij hoeft te weten. Het gaat erom WAT ie doet, en niet HOE ie het doet.
Kris Peeters
23-10-2013 15:15
Laat me even de boel wat omgooien: men zou veel vlugger dingen in een functie moeten steken.

Om bij het onderwerp te blijven ...

Als er ergens een aantal lijnen onder mekaar staan, en die lijnen code vergen commentaar; is de kans groot dat je die lijnen code beter in een functie steekt.
Dan zet je commentaar boven die functie.

Dus, wanneer je je afvraagt of er binnen een functie (of globaal) commentaar moet zijn;
vraag je eerder af of die code wel in die functie past.
Ozzie PHP
23-10-2013 15:18
Correct Kris!
Donny Wie weet
23-10-2013 15:52
In principe is het niet nodig om te commentaren als je code 100% oop is.

class Form {
private function newInputField(){
}

private function renderForm(){
}
}

Dan word er al duidelijk gemaakt wat wat is en wat wat doet of ben ik nou....? :P
E
Erwin H
23-10-2013 16:33
De eerste programmeur die voor mij werkt en geen commentaar bij zijn code zet (OOP of niet) wordt op staande voet ontslagen. Heb je enig idee hoeveel extra tijd je kwijt bent aan het interpreteren van de code als er geen commentaar bij staat? Code zonder commentaar is als een zwarte doos. Als je het moet gaan aanpassen kan je net zo goed opnieuw beginnen, dat is 9 van de 10 keer sneller.



disclaimer: ik heb op dit moment geen personeel in dienst, dus niemand hoeft voor zijn baan te vrezen.
Ozzie PHP
23-10-2013 17:16
@Donny:

Nee, JIJ weet wat die functies doen, maar ik bijv. niet. Gewoon even een regeltje commentaar erbij en klaar is Clara.

private function newInputField()

Oké, leuk wat doet ie? Returnt ie een new input field? Set ie het? Voegt ie het toe aan een bestaand formulier?

Sowieso is dit geen goede functienaam. In een goede functienaam zit een werkwoord, bijv. createInputField, of getInputField.

Reageren

Inloggen om te reageren