[PHP] Commentaar bij programmeersel

[Verwijderd]

Zoals elke goede programmeur begin ik heel enthousiast aan mijn code, loop ik af en toe vast, drink ik liters koffie en rook ik verschillende pakjes sigaretten, bezoek ik verschillende malen GOT en laat me ook helpen om uiteindelijk, na onbepaalde tijd, heel fier te zijn op mijn programmeersel en nergens gehoor te krijgen bij niet-N.E.R.D.-friends die niet begrijpen waarom ik mijn tijd aan zoiets wil verknoeien.

Wanneer ik een maand later iets mag/moet veranderen aan mijn code, heb ik enkele dagen nodig om te begrijpen wat ik ook al weer geschreven heb, omdat de code op ogenblik van schrijven duidelijk was en ik het systematisch nalaat om mijn code van commentaar te voorzien.

Maar nu ga ik eindelijk mijn leven beteren. Mijn code zal van commentaar voorzien worden!

Na deze veel te lange inleiding, eindelijk mijn vraag:
Zijn er methodieken om commentaar te schrijven of niet?
- schrijf je gewoon wat een functie doet en hoe je die moet oproepen?
- geef je uitleg bij elke controlestructuur?
- Wanneer schrijf je teveel commentaar?
- Word het document niet te zwaar om te parsen? Met commentaar word je file toch al gauw dubbel zo groot.
- ...

[Flapp]

Zelf schrijf ik alleen commentaar bij een functie als niet gelijk duidelijk is wat hij doet:

PHP:

<?php
function sayBla()
 {
   print("Bla");  
 }
?>

is natuurlijk duidelijk.

meestal aan het begin van een controle structuur een klein beetje commentaar om uit te leggen waar hij op gebasseerd is en waar hij voor dient, teveel commentaar kan natuurlijk geen kwaad.

In php word commentaar niet geparsed, en word het gewoon overgeslagen als hij het tegenkomt.

[ Voor 97% gewijzigd door Flapp op 24-07-2007 13:30 ]

[Graaf]

Ik doe zelf altijd alles commenten volgens PHPDoc ( http://www.phpdoc.org/ )

[Verwijderd]

Ik gebruik dezelfde manier van commentaar zoals bij Java.

Java:

/**
* @author: 
* @version:
* @throws:
*/

Je moet ze maar eens opzoeken(Javadoc), er zijn er een hele boel, zendstudio gebruikt die trouwens ook als ik me niet vergis

[Grijze Vos]

Naast dingen als PHPDoc/JavaDoc die ik soms wel, soms niet gebruik, gebruik ik ook vaak commentaar in mijn code op de volgende manier:

PHP:

foreach($bla as $b)
{ // uitleg over wat ik doe op elk element

  $b = $b + 1;  
}

[Verwijderd]

Commentaar voeg je toe op het moment dat je weet dat je later misschien problemen gaat krijgen bij het teruglezen. Bij twijfel altijd doen. Daarnaast is voor elke functie een korte beschrijving geen slecht idee.

Je hebt voor PHP PHPDoc en voor java JAVADoc. Dit houdt in dat je je commentaar op een bepaalde manier samenstelt (kun je genoeg over vinden bij google). Hierna kun je je pagina door een parser gooien en die maakt er een mooie overzichts pagina van waarin alle methode en functies op een rijtje worden gezet (JAVA voorbeeld).

Verder wordt het absoluut niet te zwaar voor de parser. Alles tussen /* en */ of na een // wordt gewoon simpelweg genegeerd.

[Verwijderd]

Ik geef aan zowat elk lijntje code commentaar mee. Wanneer er veel code is splits ik de code op in delen met behulp van een regeltje streepjes, als afscheiding tussen functies bijvoorbeeld:

code:

///// Korte omschrijving functie f1
function f1() {
    
    // Comment
    $var = 1;
    
    return $var;
    
} // function f1()


// -=-=-=-=-=-=-=-=-=-


///// Korte omschrijving functie f2
function f2() {
    
    // Comment
    $var = 2;
    
    return $var;
    
} // function f2()

Wanneer die functies ook nog eens heel lang zijn splits ik stukken code die bij elkaar horen in de functie ook nog een keer op met een regel streepjes ( // ---------- ).

[Verwijderd]

Verwijderd schreef op dinsdag 24 juli 2007 @ 14:14:
Ik geef aan zowat elk lijntje code commentaar mee. Wanneer er veel code is splits ik de code op in delen met behulp van een regeltje streepjes, als afscheiding tussen functies bijvoorbeeld:

code:

///// Korte omschrijving functie f1
function f1() {
    
    // Comment
    $var = 1;
    
    return $var;
    
} // function f1()


// -=-=-=-=-=-=-=-=-=-


///// Korte omschrijving functie f2
function f2() {
    
    // Comment
    $var = 2;
    
    return $var;
    
} // function f2()

Wanneer die functies ook nog eens heel lang zijn splits ik stukken code die bij elkaar horen in de functie ook nog een keer op met een regel streepjes ( // ---------- ).

Dan ben jij een goeie programmeur, ik kan het nog steeds niet opbrengen om overal commentaar te plaatsen maar het is iets waar je veel volharding voor nodig hebt.

Ik wist niet dat PHPDoc ook bestond, ik dacht gewoon dat het een afkooksel was van JavaDoc, het is wel super handig als je klasses begint over te nemen van andere mensen dat je een doc file hebt om de werking ervan te weten, ook voor jezelf een doc aanmaken is super handig, in Java doe ik dat toch altijd. Hopelijk evolueerd PHP ook zo, met een online klassenbibliotheek en volledig OO, dit zou PHP wel moeilijker maken voor veel mensen maar het zou veel netter werken

[Verwijderd]

Veel mensen gebruiken Hoare voor commentaar, dat werkt over het algemeen vrij goed.

Eventueel aangevuld door een kleine omschrijving, dat moet je zelf weten.

Daarnaast helpt het om goede zelfdocumenterende code te schrijven, dus goede functienamen, goede variabelenamen etc. De tijd dat een variabele maar 1 letter lang mocht zijn is al lang en breed voorbij, ben dus niet bang een variabele goed lang uit te schrijven.

Dat beetje tijd dat je verliest bij het typen win je gemakkelijk terug mocht je ooit de code willen nalezen.

[TeeDee]

Verwijderd schreef op dinsdag 24 juli 2007 @ 14:14:
Ik geef aan zowat elk lijntje code commentaar mee. Wanneer er veel code is splits ik de code op in delen met behulp van een regeltje streepjes, als afscheiding tussen functies bijvoorbeeld:

[...]

Wanneer die functies ook nog eens heel lang zijn splits ik stukken code die bij elkaar horen in de functie ook nog een keer op met een regel streepjes ( // ---------- ).

En wat zet jij dan in //Comment? Dat het een int of een return value is? Dan lijkt me dat compleet overbodig.

De stijl (dus .Net/Java style) maakt niet uit, maar wat voor commentaar.

- Korte beschrijving methode
- Return value kan overbodig zijn, omdat dit al bepaald is. (public int ...)
- Mogelijke Exceptions.

Commentaar in je method wordt overbodig als je bijvoorbeeld

C#:

//Start While Lus
while(MyDataAdapter.Read())
{
 ...
}

gaat vertonen.

Het is handiger als je in je method commentaar plaatst waarom je iets doet. Iedereen kan wel zien dat je een loop, while of weet ik veel wat start, je een int / string / bool / whatever declareert.

[Verwijderd]

Bedankt voor de vele antwoorden (man dat gaat hier snel).

PHPDoc lijkt mij interessant, maar wel enorm veel werk om al je code van zoveel commentaar te voorzien. Hoare lijkt mij ongemeen moeilijk...

Ik mag eerlijk zeggen dat mijn functies en variabelen namen behoorlijk goed gekozen zijn...

[Grijze Vos]

Verwijderd schreef op dinsdag 24 juli 2007 @ 14:52:
Veel mensen gebruiken Hoare voor commentaar, dat werkt over het algemeen vrij goed.

Dat heeft echt alleen maar nut bij pure algoritmiek. In gangbare code is dat echt onbruikbaar hoor.

[TeeDee]

Grijze Vos schreef op dinsdag 24 juli 2007 @ 14:55:
[...]

Dat heeft echt alleen maar nut bij pure algoritmiek. In gangbare code is dat echt onbruikbaar hoor.

Dat wou ik net zeggen. Had ooit iets over Hoare gehoord, maar niet in combinatie met 'normale' scripting / code.

Edit:

Ah, Precondition, Processing en PostCondition klinkt me bekender in de oren

[ Voor 11% gewijzigd door TeeDee op 24-07-2007 14:59 ]

[Verwijderd]

Grijze Vos schreef op dinsdag 24 juli 2007 @ 14:55:
[...]

Dat heeft echt alleen maar nut bij pure algoritmiek. In gangbare code is dat echt onbruikbaar hoor.

Nee hoor, gewoon de precondities, de verwerking en de postcondities. Dat is een hele normale manier van documenteren en is overal op toepasbaar. Let wel dat bij Hoare je gewoon pseudocode of zelfs een omschrijving kunt gebruiken, je hoeft dus niet pure wiskundige algoritmes te gebruiken al is dat soms wel handiger.

Nog een tip: Splits zoveel mogelijk op.

Probeer je functies zo kort mogelijk te houden en hou in 1 functie alleen dat wat je daadwerkelijk doet. Dat helpt ook bij het correct benoemen van de functies.

Soms zie je functies die echt huge zijn, dan weet je dat je verkeerd bezig bent.

[ Voor 11% gewijzigd door Verwijderd op 24-07-2007 14:59 ]

[Grijze Vos]

Verwijderd schreef op dinsdag 24 juli 2007 @ 14:57:
[...]

Nee hoor, gewoon de precondities, de verwerking en de postcondities. Dat is een hele normale manier van documenteren en is overal op toepasbaar. Let wel dat bij Hoare je gewoon pseudocode of zelfs een omschrijving kunt gebruiken, je hoeft dus niet pure wiskundige algoritmes te gebruiken al is dat soms wel handiger.

Mja, dan noem ik het geen Hoare logica meer hoor. Het idee van Hoare logica is nou juist dat je axiomatisch kunt bewijzen dat je programma correct is. Persoonlijk vind ik die pre/post conditie methode bij OO programmeren vaak onzinnig. Soms is het inderdaad handig dat je bepaalde precondities erbij zet, maar eigenlijk moet je toch al guarden tegen die precondities in die functie zelf, ondanks dat het contract zegt dat iets niet mag.

En ja, als ik een functie bouw die variabele $leeftijd heeft als invoer, dan ga ik echt niet vermelden dat dat ding niet negatief kan zijn.

Voor de TS, mocht je geinteresseerd zijn in deze annotatie vorm, google dan op Design by Contract.

[BikkelZ]

De stijl of standaard van becommentarieren is totaal niet belangrijk vergeleken bij het feit dat je het altijd netjes moet blijven doen. Wat bij mij wel vaak helpt is dat voordat ik een regel 'echte' code geschreven heb, ik dus een lege klasse aanmaak met alle variabelen en functies, en die dan beschrijf voordat ik ze feitelijk begin in te vullen.

In feite is dit iets wat iedere 'professionele' programmeur doet (even heel kort door de bocht ), je begint namelijk eerst met een relatiediagram, wat ieder object zou moeten kunnen, wat een functie doet en ontvangt en retourneert qua variabelen, etcetera. Dit neem je dus min of meer al direct mee op het moment dat je begint met coden. Scheelt al een boel.

Als je jezelf dan aanleert om bij ieder deel even aan te geven wat je gaat doen of waarom je het doet of waarom je op dat moment een if/then gebruikt, etc. etc. etc., dan heb je echt wel een net becommentarieerd programma geschreven, en als je dan eens een functie aanpast ben je toch ook veel sneller geneigd ook even het commentaar aan te passen.

Zelfs bij eenvoudige PHP scripts die gewoon totaal niet OO zijn, ga je toch altijd even nadenken over wat je gaat doen. Soms maak ik zelfs eerst een soort van beslisboom van commentaar die ik een paar keer doorloop voordat ik feitelijk begin te coden.

[Guldan]

ik gebruik persoonlijk altijd zoiets

PHP:

<?php
/*
* function getMessageById($id)
*
* this function gets the requested message
*
* input: the id of the message that has to be showed
* returns: a text string containing the message
*/

function getMessageById($id)
{

}
?>

En indien in de functie onduidelijkheden zijn dan geef ik die aan met // commentaar. Ik vind commentaar wel nuttig maar het kan zijn doel ook voorbijschieten. Commentaar moet iets duidelijk maken...Bij een simpele getter/setter vind ik het persoonlijk niet nodig.

IK vnid persoonlijk een stijl als die van Kyokushinkai wel heel erg over the top. Maar iedereen heeft zijn eigen stijl.

[ Voor 17% gewijzigd door Guldan op 24-07-2007 16:25 ]

[Verwijderd]

PHPDoc, where have you been all my life

Het is niet alleen leuk om je code van commentaar te voorzien, maar de output is zo snel, gemakkelijk en clean, dat het eigenlijk verplichte kost zou moeten worden

[aex351]

Ik gebruik de .NET programmeer standaard en de JAVA comment style voor PHP.

PHP:

class MijnClass implements IMijnInterface
{
    public  $mijnVar
    /* tegen de .net coding standard in gebruik ik 
     * een underscore, variant op "Hungarian notation"
     * maar dit maak ik goed in de getter van deze eigenschap
     */
    private $_mijnVar
    
    //Tada 
    public function GetMijnVar()
    {
        return $this->_mijnVar;
    }
    
    
    /**
     * Zoals gespecificeerd door IMijnInteface
     * Bedoeld als voorbeeld methode.
     * @parameter string $mijnParameter Dit is een lege parameter
     * @return void
     */
    private function MijnMethode($mijnParameter)
    {
        if(is_string($mijnParameter))
        {
            echo '$mijnParameter is inderdaad een string'. $mijnParameter;
        }
    }
}
$object = new MijnClass();
$object->MijnMethode("Een String");

Kortom, niet alleen het commentaar is belangrijk bij de code, maar ook de gebruikte benamingen voor de code. Dit punt heeft mij echt een paar jaar bezig gehouden. Voor PHP is er geen globale coding standaard. Zend, het commerciële bedrijf achter PHP, heeft met de Zend Framework ook een coding standaard neergezet. Ik heb geen idee hoever ze deze standaard willen doorpushen in de PHP gemeenschap en de kans van slagen.

Om toch meer zekerheid te hebben gebruik ik nu sinds kort de .Net coding standaard voor PHP, ben er tevreden mee. Het is duidelijk en Logisch. Alles staat tot in de detail aangegeven van hoe het wel en niet moet. http://msdn2.microsoft.co...rary/xzf533w0(vs.71).aspx.

Bovendien mocht je ooit nog met een .Net werken dan is de omschakeling snel gemaakt.

Voor commentaar gebruik ik (deels) de Java Documentatie notatie of een variant erop.

[ Voor 72% gewijzigd door aex351 op 24-07-2007 17:12 ]

[Gonadan]

Verwijderd schreef op dinsdag 24 juli 2007 @ 16:30:
PHPDoc, where have you been all my life

Het is niet alleen leuk om je code van commentaar te voorzien, maar de output is zo snel, gemakkelijk en clean, dat het eigenlijk verplichte kost zou moeten worden

/me vraagt zich af onder welke steen bweirk heeft gezeten


Zelf maak ik er ook gebruik van maar dat is voortgekomen uit het feit dat ik veel JAVA programmeerde en dus automatisch javadocs ging schrijven.
Ik ben redelijk snel PHPDocs tegen gekomen en is in mijn ogen het absolute minimum wat je aan commentaar in je code dient te zetten.
Zoals al eerder aangegeven is het een goed idee om je commentaar nog aan te vullen op lastige plaatsen in je code. Zeker als je niet de enige bent die er ooit aan gaat werken.

[doctormetal]

Waarom wordt doxygen hier nergens genoemd?
Maak ik zowel prive als zakelijk gebruik van. Ben er zeer tevreden over.

[Verwijderd]

Tot voor kort heb ik nooit echt grote (ingewikkelde) applicaties geschreven waardoor het niet echt nodig was om code van commentaar te voorzien. Een php-formke of simple nieuws-query'ke moeten nu niet echt uitgelegd worden

Nu ik eindelijk eens een groot project onder handen neem, is het duidelijk dat dit van commentaar voorzien moet worden. En als je nooit commentaar geschreven hebt en/of op zoek bent gegaan naar methodes voor het schrijven van commentaar, kom ik niet van onder een steen maar een massief gebergte gekropen

[Verwijderd]

PHPdoc doet echt wel geweldig werk en geeft me functionaliteiten waar ik zelfs niet van kon dromen. Echt de droom voor elke PHP-programmeur.

Jammergenoeg kom je zo weer in contact met je eigen code, zie je je stommiteiten of denk je: "waarom heb ik dit weer zo gedaan" en verlies je enorm veel tijd door alles te willen opkuisen...

Nogmaals bedankt voor de goede hulp.

[sopsop]

Verwijderd schreef op dinsdag 24 juli 2007 @ 23:42:
[..] en verlies je enorm veel tijd door alles te willen opkuisen...[..]

Dat is korte termijn denken. Op langere termijn win je er alleen maar tijd mee.

[PrisonerOfPain]

Grijze Vos schreef op dinsdag 24 juli 2007 @ 15:12:
Persoonlijk vind ik die pre/post conditie methode bij OO programmeren vaak onzinnig.

Meestal vind ik het ook onzinnig, maar bij het toepassen van overerving is het vaak wel handig om het Liskov substitution principle in het achterhoofd te houden. Zeker als de overerving pas later in het project voorkomt kan het wel handig zijn.

[Observer]

PHPDoc gebruiken geeft als bijkomend voordeel dat Zend Studio code completion beter kan gaan toepassen.