commentaar... hoe ver ga je?
Ik ben benieuwd hoe ver jullie gaan met het becommentarieren van functies/method.
Normaal zou ik bijvoorbeeld dit doen:
Code (php)
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
<?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);
}
?>
// 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:
Code (php)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?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);
}
?>
// 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.
Gewijzigd op 21/10/2013 17:17:01 door Ozzie PHP
En dat is dus precies wat ik me ook afvraag!
Nog meer meningen?
Je moet vertellen wat je van plan bent.
Je moet niet uitleggen wat een functie, die je gebruikt, doet. Daarvoor bestaat de reference.
bv.
- Jouw lijn 12 lijkt me vrij zinloos. Als ik wil weten wat array_merge doet, kijk ik op php.net
De code spreekt voor zich.
- Een zelfgemaakte functie verdient (wat mij betreft) bijna altijd een woordje uitleg.
Dat staat bij mij boven de functie, in dit geval:
// Add new paths to the existing paths.
Maar is dat voldoende vind jij? Of moet die uitleg in de functie zelf (voorbeeld 2) er ook nog bij.
>> Je moet niet uitleggen wat een functie, die je gebruikt, doet. Daarvoor bestaat de reference.
Wat bedoel je hier dan mee?
Code (php)
Hier vertel je iets wat elke developer beter van php.net zelf te horen krijgt.
Dat soort dingen moet je dus niet doen.
----
Nog een voorbeeld van mezelf. Onlangs stond dit hier op dit forum ...
Code (php)
1
2
3
2
3
$('#set_user').on('submit', function(e) {
e.preventDefault(); // dit zorgt dat het formulier niet wordt verzonden op klassieke manier
var data = $(this).serialize(); // $(this) is hier het formulier. serialize zet de gegevens van het formulier om in een object
e.preventDefault(); // dit zorgt dat het formulier niet wordt verzonden op klassieke manier
var data = $(this).serialize(); // $(this) is hier het formulier. serialize zet de gegevens van het formulier om in een object
Als ik dit commentaar schreef, was dat om iets duidelijk te maken aan de topic starter.
Maar in een afgewerkt product is dit commentaar vrij nutteloos en zou ik het verwijderen.
-----
Hier een ander voorbeeld. Iets met Youtube API.
Je ziet amper een rechtstreeks verband tussen het commentaar en de code.
Maar je vertelt wat het plan is; wat de bedoeling is.
Code (php)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
...
// 4. The API will call this function when the video player is ready.
function onPlayerReady(event) {
event.target.playVideo();
}
// 5. The API calls this function when the player's state changes.
// The function indicates that when playing a video (state=1),
// the player should play for six seconds and then stop.
function onPlayerStateChange(event) {
if (event.data == YT.PlayerState.PLAYING && !done) {
done = true;
}
}
...
// 4. The API will call this function when the video player is ready.
function onPlayerReady(event) {
event.target.playVideo();
}
// 5. The API calls this function when the player's state changes.
// The function indicates that when playing a video (state=1),
// the player should play for six seconds and then stop.
function onPlayerStateChange(event) {
if (event.data == YT.PlayerState.PLAYING && !done) {
done = true;
}
}
...
-----
Je hoort me niet zeggen dat ik de beste en slechtste voorbeelden geef.
Maar ik hoop dat je het algemene idee begrijpt
Gewijzigd op 21/10/2013 17:55:07 door Kris Peeters
1) PHPdoc waar nodig
PHPdoc gebruik ik niet te overmatig, dingen als:
Code (php)
Zou ik niet doen, het is wel duidelijk dat getName de name get... Dus ik zou alleen @return string erin zetten.
Ook bijv. configure(array $options). Hierbij zou ik de "@param array $options The options" regel gewoon helemaal weglaten, overbodige onzin.
2) Inline comments bij lange code
In de meeste gevallen bevatten methods weinig code en is alles wel overzichtelijk. Soms zijn er echter heel veel dingen, dan gebruik ik inline comments om de code duidelijker te maken. Voor 2 voorbeelden: https://github.com/sensiolabs/SensioGeneratorBundle/pull/157/files#diff-c62ea5305afdcb73392777c1b32f224eR33 en https://github.com/symfony/symfony/pull/8635/files#diff-185e8e5e0567b6525f1b3e67c8cb7d99R50
Dan gebruik ik de blok-methode met /* Beeeh! */, ondaks ik vaak maar een enkele regel gebruik.
Volgens phpStorm (de IDE die ik gebruik) kent mijn code wel een hoop ToDo's in de comments.
Grappig dat deze daarin kan scannen, zodat ik weet wat ik ooit nog eens moet aanpassen.
Heel soms kom ik wel eens vrolijke comments tegen zoals deze:
Code (php)
1
2
3
4
2
3
4
// Een prachtwerkje van Arin, hij doet het prima, en toont de categorieen in de array.
// Er worden twee queries gebruikt in dit script omdat het met JOINS niet mogelijk leek.
// Had het graag anders gewild, maar het lijkt uit te komen op deze constructie.
// Wie beter weet, mag het zeggen in ruil voor een kopje appelthee.
// Er worden twee queries gebruikt in dit script omdat het met JOINS niet mogelijk leek.
// Had het graag anders gewild, maar het lijkt uit te komen op deze constructie.
// Wie beter weet, mag het zeggen in ruil voor een kopje appelthee.
In dit geval nog verouderd, omdat het nog line-commenting is, waar ik niet meer aan doe ;-)
Nu nog eens uitzoeken hoe ik die code beter kan maken :-P
In geval van classes en methods, zorgt PHPstorm wel voor de nodige function-comments (PHPdoc)
Gewijzigd op 21/10/2013 19:21:43 door - Ariën -
# Here foo happens.
// code
// code
// code
# Here bar happens.
// code
// code
// code
# Here foobar happens.
// code
// code
// code
Thanks voor het meedenken.
Als je je eigen functie- en variabelenamen zorgvuldig kiest, is je code als het ware zelfdocumenterend. Je hoeft er dan niet nog eens met een commentaarregeltje bij te zeggen wat die functie of variabele doet. Hetzelfde geldt voor API-functies; daar is voldoende documentatie van te vinden op het net.
Alleen wanneer een functienaam net te algemeen is om als documentatie te dienen zou ik in commentaar een beschrijving geven.
Stel dat je een functie vindGrootsteGemeneDeler($x,$y) hebt. Het kan dan handig zijn om in je commentaar iets te zeggen als "Trek, zolang $x en $y niet gelijk zijn, het kleinste van het grootste getal af. Wanneer $x en $y gelijk zijn, is de gevonden waarde de grootste gemene deler."
Daarnaast is het waardevol om aan te geven waarom je iets op een bepaalde manier doet. Dat kan voorkomen dat je een jaar later die code bekijkt, denkt "Hé, dat kan efficiënter/beter/handiger" en er na een dag pielen achter komt dat het toch alleen op de oude manier werkt. Vooral wanneer de kans bestaat dat iemand anders ooit aan die code moet sleutelen is dat handig. Ik sta nu voor de klus om een website (interne portal) van zo'n 30 duizend regels VBscript/MSSQL te herschrijven in Perl/PHP/MySQL en zit me regelmatig af te vragen waarom de programmeur destijds dingen op een bepaalde manier heeft opgelost.
Code (php)
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
/*
* people making love
* never exactly the same
* just like a snowflake
*/
void
Ignore(int a)
{
a = a;
}
* 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...
En dan een wazige tekst erboven. In denk dat de schrijver ervan onder invloed was!
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.
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.
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.
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
disclaimer: ik heb op dit moment geen personeel in dienst, dus niemand hoeft voor zijn baan te vrezen.
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.