[alg] Commentaar in code nodig of overbodig?

[Michali]

vgouw schreef op dinsdag 20 september 2005 @ 15:18:
[...]

Daar hebben ze commentaar voor uitgevonden.

Dat is imo gewoon een erg foute opvatting. Je moet altijd coden op zo'n manier dat je code zo begrijpelijk mogelijk is. Als dat niet lukt dan is je code slecht of is het een dermate moeilijk onderwerp dat de code niet snel te snappen is. Als je veel moet gaan ondersteunen met commentaar dan is dat vaak een teken dat je code gewoon niet duidelijk genoeg is. Wat helpt is dan je code goed structureren, duidelijke en consequente namen gebruiken voor functies/vars etc. en alles opdelen in duidelijke (kleine) taken in aparte functies, oftewel: refactoren.

[vinnux]

Michali schreef op dinsdag 20 september 2005 @ 15:33:
[...]


Dat is imo gewoon een erg foute opvatting. Je moet altijd coden op zo'n manier dat je code zo begrijpelijk mogelijk is. Als dat niet lukt dan is je code slecht of is het een dermate moeilijk onderwerp dat de code niet snel te snappen is. Als je veel moet gaan ondersteunen met commentaar dan is dat vaak een teken dat je code gewoon niet duidelijk genoeg is. Wat helpt is dan je code goed structureren, duidelijke en consequente namen gebruiken voor functies/vars etc. en alles opdelen in duidelijke (kleine) taken in aparte functies, oftewel: refactoren.

Ik heb liever slechte code met commentaar dan goede code zonder commentaar!
Wat goede en begrijpelijk code is voor de een is vaak abracadabra voor de ander. Ook als is het zogenaamde goed geschreven code. Zonder commentaar geen leven in programmeer land.

[Verwijderd]

vgouw schreef op dinsdag 20 september 2005 @ 16:09:
Ik heb liever slechte code met commentaar dan goede code zonder commentaar!
Wat goede en begrijpelijk code is voor de een is vaak abracadabra voor de ander. Ook als is het zogenaamde goed geschreven code. Zonder commentaar geen leven in programmeer land.

Hangt van het type commentaar af, van die one-liners heb je niks aan, en zijn (altijd) overbodig. Functie en klasse beschrijvingen niet.

[Erkens]

Verwijderd schreef op dinsdag 20 september 2005 @ 16:15:
[...]

Hangt van het type commentaar af, van die one-liners heb je niks aan, en zijn (altijd) overbodig. Functie en klasse beschrijvingen niet.

die zijn voor jou wellicht overbodig, maar als een ander jouw code leest dan is die vaak erg blij dat je even een korte toelichting geeft

[Verwijderd]

Erkens schreef op dinsdag 20 september 2005 @ 16:31:
die zijn voor jou wellicht overbodig, maar als een ander jouw code leest dan is die vaak erg blij dat je even een korte toelichting geeft

Euh nee, absoluut niet. Ten eerste hoeft iemand de inhoud van de methode niet te kunnen lezen. Want hij/zij zou voldoende moeten hebben aan de documentatie van de methode zelf. Ten tweede is code 'fout' (functie/attribuut namen alsmede de flow) als het commentaar behoeft.

[Michali]

vgouw schreef op dinsdag 20 september 2005 @ 16:09:
[...]

Ik heb liever slechte code met commentaar dan goede code zonder commentaar!
Wat goede en begrijpelijk code is voor de een is vaak abracadabra voor de ander. Ook als is het zogenaamde goed geschreven code. Zonder commentaar geen leven in programmeer land.

Ooit van self documenting code gehoord? (ok, je kunt die op meerdere manieren opvatten, maar voor mij betekent het dat code zo duidelijk is dat je vrijwel geen comments nodig hebt. andere documentatie is vrijwel altijd nodig) Ik ben het hier absoluut niet met je eens. Goede code heeft bijna geen comments nodig. De comments zitten dan in princiepe verwerkt in de namen van de functies en de variabelen, en verder heeft het een logische structuur die de intentie ook nog eens ondersteund. Slechte code heeft dat niet. Dan kun je dat wel gaan proberen te verbergen met comments, maar dan ben je imo fout bezig. Een comment is imo pas nodig als een statements zo complex is dat hij wel wat extra uitleg verdient. Soms kun je dat zelfs voorkomen door hem in een aparte functie te zetten (maar dat is meer een smaak kwestie). Als je gewoon zorgt dat een functie een duidelijke taak heeft en een naam die die taak duidelijk en geheel vertelt, dan ben je al een heel eind.

Laten we je code er even bijpakken en kijken wat er allemaal mis mee is:

PHP:

<?//Dynamically find the config file and calculate the relative path for the config file
if (!defined('REL')) {     
  $rel                             = '';
  $REL_CONFIG_FILE     = 'config.inc.php';
  $REL_DEPTH             = 0;
  $REL_MAX_DEPTH         = 10;
  $REL_FOUND                 = file_exists($rel.$REL_CONFIG_FILE);
     while (!$REL_FOUND && $REL_DEPTH < $REL_MAX_DEPTH) {
       $REL_DEPTH++;
        $rel.="../";
        $REL_FOUND = file_exists($rel.$REL_CONFIG_FILE);
     }
     if($REL_FOUND === true) {
         require_once($rel.$REL_CONFIG_FILE);
         unset($rel,$REL_DEPTH,$REL_MAX_DEPTH,$REL_FOUND);
     } else {
       //The config file could not be found. The page cannot bedisplayed
         die('FATAL : '.$REL_CONFIG_FILE.' not found');    
     }
} 
require_once(REL.'-inc-/pageGui.inc.php');                //Displaying functions ?>

Ten eerste is het in 1 oog opslag niet duidelijk wat de taak is van de code. Dit ondersteund je met een comment. Dit is imo vrij gemakkelijk te voorkomen door middel van het verplaatsen van de code naar een aparte functie. Verder ben je inconsequent met variabel namen. Je gebruikt conventies voor constanten voor normale variabelen (namelijk $REL_DEPTH en $REL_FOUND, die geef je later weer een nieuwe waarde), beter is om voor echte constanten define() te gebruiken en voor normale variablen een andere wijze van schrijven te gebruiken ($relDepth en $relFound). $rel is verder te weinig informatief. Je ziet niet in 1 oogopslag waar de variabel voor wordt gebruikt. Je kopieert ook nog eens statements die makkelijker in 1 keer kunnen. (bij de while lus).

Hier volgt dan mijn versie (niet getest) zonder commentaar:

PHP:

<?

function dynamicallyFindFilePath($fileToFindPathFor, $maxDepth)
{
    $relativePath= "./";
    $currentDepth = -1;
    do
    {
        $currentFilePath = $relativePath . $fileToFindPathFor;
        if ( file_exists($currentFilePath) ) return $currentFilePath;
        $relativePath .= "../";
        $currentDepth++;
    } while ( $currentDepth < $maxDepth);
    return null;
}

if ( !defined('REL') )
{
    define('CONFIG_FILE_NAME', 'config.inc.php');
    define('DYNAMIC_FIND_MAX_DEPTH', 10);
    
    $configFilePath = dynamicallyFindFilePath(CONFIG_FILE_NAME, DYNAMIC_FIND_MAX_DEPTH);
    $configFileIsNotFound = $configFilePath == null;
    if ( $configFileIsNotFound )
    {
        die('FATAL : ' . CONFIG_FILE_NAME . ' not found');
    }
    require_once($configFilePath);
}
require_once(REL . '-inc-/pageGui.inc.php');

?>

Ik heb er zelfs een algemene functie uit weten te halen die niet alleen voor config file bruikbaar is. Ik gebruik duidelijke namen en conventies en pas self-documenting code technieken toe. Imo is het zo een stuk duidelijker.

[ Voor 13% gewijzigd door Michali op 20-09-2005 17:10 ]

[dossiewossie]

Verwijderd schreef op dinsdag 20 september 2005 @ 16:39:
[...]
Euh nee, absoluut niet. Ten eerste hoeft iemand de inhoud van de methode niet te kunnen lezen. Want hij/zij zou voldoende moeten hebben aan de documentatie van de methode zelf. Ten tweede is code 'fout' (functie/attribuut namen alsmede de flow) als het commentaar behoeft.

Okee, hoe zit het met mn flow + functie/attribuutnamen?

[Erkens]

Verwijderd schreef op dinsdag 20 september 2005 @ 16:39:
[...]
Euh nee, absoluut niet. Ten eerste hoeft iemand de inhoud van de methode niet te kunnen lezen. Want hij/zij zou voldoende moeten hebben aan de documentatie van de methode zelf. Ten tweede is code 'fout' (functie/attribuut namen alsmede de flow) als het commentaar behoeft.

offtopic:
ben ik even blij dat ik niet met jou hoef samen te werken
zodra je alleen werkt dan boeit het idd weinig, je rommelt wat aan en als je over een paar maanden wat wilt aanpassen herschrijf je het gewoon, in een bedrijfsomgeving kan je dat gewoon niet maken

[Grijze Vos]

Verwijderd schreef op dinsdag 20 september 2005 @ 16:15:
[...]

Hangt van het type commentaar af, van die one-liners heb je niks aan, en zijn (altijd) overbodig. Functie en klasse beschrijvingen niet.

Je wilt mn Z-80 assembly (Ti-83+) echt niet lezen zonder de one-liners hoor. Dan sterf je echt van een shock.

[Verwijderd]

Erkens schreef op dinsdag 20 september 2005 @ 19:11:

offtopic:
ben ik even blij dat ik niet met jou hoef samen te werken
zodra je alleen werkt dan boeit het idd weinig, je rommelt wat aan en als je over een paar maanden wat wilt aanpassen herschrijf je het gewoon, in een bedrijfsomgeving kan je dat gewoon niet maken

Mwoah hangt er vanaf hoe professioneel je bedrijfsomgeving is. Dus ja ik ben ook blij dat ik niet met jou samen hoef te werken

[NMe]

Verwijderd schreef op woensdag 21 september 2005 @ 09:42:
Mwoah hangt er vanaf hoe professioneel je bedrijfsomgeving is.

Een bedrijf dat zichzelf ook maar een heel klein beetje respecteert doet alles aan duidelijkheid en herbruikbaarheid van code. Zelfs als je op dat moment de enige developer bent die aan een stuk code werkt, dan nog moet je het voorzien van duidelijk commentaar. Reden? Je code is eigendom van je baas. Je baas kan er later nog iemand anders aan laten werken, en die moet ermee vooruit kunnen. Een bedrijf dat niet zo te werk gaat is onprofessioneel bezig en komt zichzelf snel genoeg tegen.

Dus ja ik ben ook blij dat ik niet met jou samen hoef te werken

Dan ben je blijkbaar blij dat je niet werkt in in die 98% van alle bedrijven die goed bezig is.

[Verwijderd]

-NMe- schreef op woensdag 21 september 2005 @ 17:23:
Een bedrijf dat zichzelf ook maar een heel klein beetje respecteert doet alles aan duidelijkheid en herbruikbaarheid van code. Zelfs als je op dat moment de enige developer bent die aan een stuk code werkt, dan nog moet je het voorzien van duidelijk commentaar. Reden? Je code is eigendom van je baas. Je baas kan er later nog iemand anders aan laten werken, en die moet ermee vooruit kunnen. Een bedrijf dat niet zo te werk gaat is onprofessioneel bezig en komt zichzelf snel genoeg tegen.

Je hebt gelijk als je zegt dat elk bedrijf dat zich maar een beetje respecteert er veel aan doet om duidelijke code op te leveren. Dat wil niet automatisch zeggen dat commentaar gebruikt moet worden. Tussen de twee zit immers geen oorzakelijk verband. Als mede ontwikkelaar wil ik graag dat een collega in de documentatie beschrijft wat een methode doet zodat ik rekening kan houden met de uitzonderingen van deze methode. Maar ik wil niet weten hoe deze methode dat doet. Op het moment dat deze methode voor refactoring in aanmerking komt zou zelf explaining code en, zeer belangrijk, de unit test de documentatie moeten zijn.

Ik begrijp dat dit tegen je manier van werken in gaat, maar sta er wel voor open. En probeer ook te begrijpen dat documentatie in de methode enkel aangeeft dat de code onduidelijk is.

-NMe- schreef op woensdag 21 september 2005 @ 17:23:
Dan ben je blijkbaar blij dat je niet werkt in in die 98% van alle bedrijven die goed bezig is.

Dit is echt een onzin uitspraak, waar baseer je dat op? Goede code behoeft nou eenmaal geen commentaar, dat is wel een feit.

[ Voor 69% gewijzigd door Verwijderd op 22-09-2005 10:33 ]

[Erkens]

Verwijderd schreef op donderdag 22 september 2005 @ 10:12:
[...]
Dit is echt een onzin uitspraak, waar baseer je dat op? Goede code behoeft nou eenmaal geen commentaar, dat is wel een feit.

een feit

Een feit is dat als je samen moet werken dat je het niet kan maken om er geen commentaar bij te zetten, een ander kan moeilijk weten waar jij aan dacht toen je die code schreef.
Heb jij overigens ooit code van jezelf gelezen van zeg een jaar geleden? Of "goede" code van een ander gelezen? en dan ook nog begrepen?

[Verwijderd]

Erkens schreef op donderdag 22 september 2005 @ 10:24:
Een feit is dat als je samen moet werken dat je het niet kan maken om er geen commentaar bij te zetten, een ander kan moeilijk weten waar jij aan dacht toen je die code schreef.
Heb jij overigens ooit code van jezelf gelezen van zeg een jaar geleden? Of "goede" code van een ander gelezen? en dan ook nog begrepen?

Ja en dat is leesbaar. hierboven staat ook een mooi voorbeeld in php van hoe het moet.
Probeer het nou eens, probeer nou eens in te denken dat je code gewoon slecht is als het commentaar behoeft. Je hebt er gewoon niet eens de moeite voor genomen om er over na te denken.

[ Voor 17% gewijzigd door Verwijderd op 22-09-2005 10:37 ]

[Erkens]

Verwijderd schreef op donderdag 22 september 2005 @ 10:34:
[...]
Ja en dat is leesbaar. hierboven staat ook een mooi voorbeeld in php van hoe het moet.
Probeer het nou eens, probeer nou eens in te denken dat je code gewoon slecht is als het commentaar behoeft. Je hebt er gewoon niet eens de moeite voor genomen om er over na te denken.

De code in dit topic is ook niet goed te lezen, je moet regel voor regel gaan uitzoeken (in je hoofd compilen) om te zien wat er gebeurd als het ware. Daarnaast zijn de voorbeelden in dit topic niet wat je noemt complex.
Gewoon 1 regeltje met wat de code moet doen en wellicht bij bepaalde statements een extra uitleg scheelt enorm op de debugtime en in de toekomst op het toevoegen van extra features etc. De tijd die het kost om dat commentaar neer te zetten vallen in het niet bij de tijd die jij of een ander later nodig hebt.

(wellicht kan een modje deze discussie afsplitsen )

[Verwijderd]

Erkens schreef op donderdag 22 september 2005 @ 10:45:
De code in dit topic is ook niet goed te lezen, je moet regel voor regel gaan uitzoeken (in je hoofd compilen) om te zien wat er gebeurd als het ware. Daarnaast zijn de voorbeelden in dit topic niet wat je noemt complex.

Dus als ik je goed begrijp vind je dat alleen complexe code in aanmerking komt voor commentaar. Mijn tegen argument is dat complexe code gerefactord dient te worden naar simpele code die geen commentaar behoeft.

[Creepy]

Even wat afgesplitst uit [rml][ php] mijn manier van paginas includen in index.php veilig?[/rml] ..

[Erkens]

Verwijderd schreef op donderdag 22 september 2005 @ 10:47:
[...]
Dus als ik je goed begrijp vind je dat alleen complexe code in aanmerking komt voor commentaar. Mijn tegen argument is dat complexe code gerefactord dient te worden naar simpele code die geen commentaar behoeft.

nee je begrijpt mij niet goed, ook niet complexe code moet commentaar bevatten.
ow sommige dinge kan je niet refactoren zonder dat het ingewikkeleder wordt waardoor je juist meer commentaar moet toevoegen, refactoren is niet een "oplossing" voor alle problemen

[ Voor 19% gewijzigd door Erkens op 22-09-2005 10:57 ]

[Verwijderd]

Erkens schreef op dinsdag 20 september 2005 @ 19:11:
[...]

offtopic:
ben ik even blij dat ik niet met jou hoef samen te werken
zodra je alleen werkt dan boeit het idd weinig, je rommelt wat aan en als je over een paar maanden wat wilt aanpassen herschrijf je het gewoon, in een bedrijfsomgeving kan je dat gewoon niet maken

^ Eensch. Als anderen jouw code moeten gebruiken zijn ze écht wel gebaat bij commentaar, ook al is het duidelijke code. Ik zet zelf bijvoorbeeld graag in het commentaar van klasses en methoden (1) waarvoor de klasse/methode dient en (2) vanuit welke andere klasses en methodes het aangeroepen wordt. Zo krijg je veel sneller een overzicht van hoe de onderdelen van de applicatie met elkaar samenwerken.

[Alarmnummer]

Ik hou zelf van wat regels commentaar in mijn code. Vooral bij kleine blokjes met code zet ik graag een regel commentaar. Ik vind in veel gevallen het niet onacceptabel om dit te refactoren naar een methode, omdat je op den duur zoveel ruis krijgt *hmmm.. heeft volgens mij dit gesprek al een keer gevoerd* binnen een class.

Ik vind dat nagenoeg alle methodes documentatie moeten hebben, alle classes, en zo nu en dan dus ook in de methode. Maar ook packages moeten documentatie krijgen waarin je in grote lijnen uitlegt wat het doel is van de package.

Vooral als je met complexe materie bezig bent zegt 1 regel commentaar meestal meer dan 5 regels code. En ik kan dan snel even door het commentaar heen wandelen om de logica van de methode te begrijpen.

[ Voor 21% gewijzigd door Alarmnummer op 22-09-2005 11:05 ]

[Verwijderd]

Tsja ik hoor het al, je blijft starrig vasthouden aan het geloof dat commentaar nodig is, zonder het ook maar te overwegen het eens vanuit een ander perspectief te benaderen. Een wanargument als "refactoren is ook niet alles" wat dus feitelijk evenveel zegt als totaal niets geeft dat wel aan.

Ik hoop dat je op andere vlakken wel bereidt bent om iets nieuws te leren/proberen.

Verwijderd schreef op donderdag 22 september 2005 @ 11:01:
^ Eensch. Als anderen jouw code moeten gebruiken zijn ze écht wel gebaat bij commentaar, ook al is het duidelijke code. Ik zet zelf bijvoorbeeld graag in het commentaar van klasses en methoden (1) waarvoor de klasse/methode dient en (2) vanuit welke andere klasses en methodes het aangeroepen wordt. Zo krijg je veel sneller een overzicht van hoe de onderdelen van de applicatie met elkaar samenwerken.

Je hebt het geloof ik iets te vluchtig gelezen. Dit is niet het type commentaar waar het om gaat in de discussie Dat dergelijk commentaar nodig is, is iedereen het over eens.

[ Voor 49% gewijzigd door Verwijderd op 22-09-2005 11:07 ]

[Alarmnummer]

Verwijderd schreef op donderdag 22 september 2005 @ 11:05:
Tsja ik hoor het al, je blijft starrig vasthouden aan het geloof dat commentaar nodig is, zonder het ook maar te overwegen het eens vanuit een ander perspectief te benaderen.

Ik heb idd met jou de discussie al een keer gevoerd. Het is toch niet zo lastig om te realiseren dat je enorm veel code ruis gaat krijgen als je iedere code fragment dat een stuk commntaar behoeft tot een functie om gaat zetten? Je krijgt dan zoveel functies die alleen een betekenis hebben in een bepaalde context.

Mijn functies zijn over het algemeen niet langer dan 10 a 15 regels, inclusief een aantal regels commentaar. Ik vind dit een erg prettig balans... niet te veel functies.. niet te lange functies.

[Verwijderd]

@alarmnummer, die opmerking was niet aan jou gericht

[Alarmnummer]

Verwijderd schreef op donderdag 22 september 2005 @ 11:11:
@alarmnummer, die opmerking was niet aan jou gericht

Dat weet ik.

Ik hoop trouwens dat deze discussie iets meer gaat worden dan op de '5 regels code + commentaar' vs '1 gerefactorde functie'

Ik ben zo nu en dan met redelijk complexe meuk bezig: asynchrone communicatie -> threading/channels, prolog compilers en searchengines. Ik heb persoonlijk vaak veel meer aan documentatie op een hoger nivo. Hoe gaat iedereen hier mee om? Zelfs commentaar op class nivo is eigelijk nog vrij nutteloos als het totaal plaatje mist. Volgens mij is deze discussie een stuk interessanter.

[ Voor 40% gewijzigd door Alarmnummer op 22-09-2005 11:14 ]

[whoami]

Ik geloof dat er hier ooit al eens een topic over deze issue geweest is, maar ik kan het niet zo direct terugvinden.

Ik vind dat commentaar in code noodzakelijk is, maar, onzinnig commentaar moet vermeden worden.
Wat bedoel ik met onzinnig commentaar ?
bv:

code:

// tel b en c op.
int a = b + c;

Dit is nu wel een stom voorbeeld, maar ik denk wel dat je snapt wat ik bedoel. Het is onzinnig om een regel code van commentaar te voorzien, als die code zelf al uitwijst wat ze doet.

Het is imho veel interessanter om een functie van commentaar te voorzien (in C# kan dat makkelijk met /// comments), waar je dus uitlegt wat die functie doet, wat de parameters zijn en wat ze returned.
Binnen een functie kan je ook wat commentaar voorzien, voor een bepaald code-blok, waarin je aangeeft wat die code doet, en waarom je het zo gedaan hebt. Commentaar kan ook voor een niet triviale regel code.

Echter, commentaar zoals ik eerder aanhaalde (die a + b regel bv) is gewoon overbodig, en vervuilt de code.

Ow, en 'self documenting code' is een utopie imho. Je zult altijd wel ergens iets hebben dat niet triviaal is, en waar wat meer uitleg welkom is.

[ Voor 7% gewijzigd door whoami op 22-09-2005 11:16 ]

[Annie]

Waarom moet altijd alles zo zwart-wit zijn?

Ja, natuurlijk moet je duidelijke code schrijven. En ja, het zou mooi zijn als de code self-documenting is. Maar in plaats van als een slechtziende mol met oogkleppen op maar roepen dat je daarom geen commentaar hoeft in te voegen, vind ik weer wat te ver gaan. Schrijven van commentaar is een middel om code duidelijk(er) te maken. Geen doel. Dus waarom zou je dat middel niet gebruiken op de juiste momenten?

Oh, en refactoren is leuk. Maar je kan niet verwachten dat er altijd maar tijd is om code (weer) te herschrijven. Dan kan een enkel regeltje commentaar alles zoveel simpeler maken.

[Alarmnummer]

whoami schreef op donderdag 22 september 2005 @ 11:15:
Ow, en 'self documenting code' is een utopie imho. Je zult altijd wel ergens iets hebben dat niet triviaal is, en waar wat meer uitleg welkom is.

Yep.. Maar wat wel kan helpen is je code beter leesbaar te maken. Vooral gechainde methode calls kunnen nog wel eens wat onoverzichtelijk worden.

Dit soort constructies bv
String s = a.getB().getC().doSomething(e.getF(),e.getG());

Die bouw ik meestal om naar iets simpelers:
f = e.getF();
g = e.getG();
c = a.getB().getC();
s = c.doSomething(f,g);

Dus je kunt vaak je code wel herschrijven zodat het beter leesbaar is.

[edit]
maar dat hoef ik jou vast niet te vertellen

[ Voor 6% gewijzigd door Alarmnummer op 22-09-2005 11:23 ]

[Not Pingu]

Michali schreef op dinsdag 20 september 2005 @ 15:33:
[...]


Dat is imo gewoon een erg foute opvatting. Je moet altijd coden op zo'n manier dat je code zo begrijpelijk mogelijk is. Als dat niet lukt dan is je code slecht of is het een dermate moeilijk onderwerp dat de code niet snel te snappen is.

Hoe wil je dan in je code aangeven dat een bepaald iets op een ongebruikelijke manier wordt gedaan om een bepaalde reden? Dat je in commentaar gaat beschrijven wat elke regel code doet, ok, dat is overbodig. Maar bijv. de functie van een lang if-statement ("check of gebruiker ingelogd is, de juiste rechten bezit en het laatste jaar tenminste 1x ingelogd heeft") of een beetje extra uitleg is in sommige gevallen heel handig.
En om dat nou alleen in de documentatie aan te geven,...

[whoami]

Alarmnummer schreef op donderdag 22 september 2005 @ 11:21:
[...]

Yep.. Maar wat wel kan helpen is je code beter leesbaar te maken. Vooral gechainde methode calls kunnen nog wel eens wat onoverzichtelijk worden.

Ik zeg natuurlijk ook niet dat gedocumenteerde code het rechtvaardigt om ongestructureerde of onleesbare code te hebben natuurlijk.
IMHO moet code zoveel mogelijk gestructureerd zijn, leesbaar zijn, mooi zijn, makkelijk te begrijpen, etc..., maar beschouw het commentaar als complementair daarbij. Hoe goed de code ook is, ze zal nooit de 'duidelijkheid' van goed commentaar kunnen vervangen.
Beiden zijn gewoon nodig.

[curry684]

Verwijderd schreef op dinsdag 20 september 2005 @ 16:15:
[...]

Hangt van het type commentaar af, van die one-liners heb je niks aan, en zijn (altijd) overbodig. Functie en klasse beschrijvingen niet.

Dit is dus je reinste onzin. Ik commentariseer altijd op een simpele manier: per 'functioneel blok' van 1 tot ~10 regels heb ik een open regel met daarachter een one-liner. Op die manier kun je blind een stuk code voor je neus krijgen, en gewoon ipv 30 regels code lezen die je ook nog moet begrijpen binnen de context van de class (members etc.) lees je enkel de 5 regels commentaar in plain English. Ik weet wel hoe je sneller het globale idee achter de functie snapt.

Self-documenting code is ook een farce. Ik schrijf uber-cleane code, maar ik commentariseer consequent. Het commentaar maakt dan ook deel uit van het uber-cleane gedeelte en misschien nog wel belangrijker het grootste gedeelte van het self-documenting idee. Even een voorbeeldstukje uit een C++ ThreadPool implementatie van paar jaar geleden:

C++:

// ------------------------------------------------------------------------
// Process: Executes a procedure within a thread of the pool
// ------------------------------------------------------------------------

void CThreadPool::Process(const RThreadProcedure &p_Procedure)
{
  BLock           l_Lock(m_AccessProtector, False);
  RPooledThread   l_Thread;
  
  // Acquire the semaphore for protected thread access
  m_ThreadAvailable->Lock();
  
  // Retrieve an available thread in protected mode
  l_Lock.Lock();
  l_Thread = m_AvailableThreads->RemoveHead();
  l_Lock.Unlock();
  
  // Execute the procedure
  l_Thread->Process(p_Procedure);
}

Als je die 3 regels in de functie leest ben je in 2 seconden klaar met het snappen van de complete internals van deze functie. Als je die ene erboven leest ben in 2 seconde klaar met snappen van de functie als geheel. Als je de code moet lezen om hetzelfde te begrijpen moet je de implementaties van 4 classes kennen en dubbel zoveel regels lezen, en dit is toch echt geen cryptische code met onduidelijke variabele- en functienamen verder.

Mensen die commentaar overbodig vinden vind ik overbodig in mijn team.

[ Voor 10% gewijzigd door curry684 op 22-09-2005 11:35 . Reden: meer decoratie ]

[Erkens]

Alarmnummer schreef op donderdag 22 september 2005 @ 11:21:
Dit soort constructies bv
String s = a.getB().getC().doSomething(e.getF(),e.getG());

Die bouw ik meestal om naar iets simpelers:
f = e.getF();
g = e.getG();
c = a.getB().getC();
s = c.doSomething(f,g);

ik vind die laatste persoonlijk wat lastiger lezen omdat je hierbij meer moet nadenken en onthouden als je even snel de code moet lezen.
uiteraard is dit een voorbeeld aangezien de functienamen natuurlijk ook niet echt mee werken

[Alarmnummer]

Erkens schreef op donderdag 22 september 2005 @ 11:35:
[...]

ik vind die laatste persoonlijk wat lastiger lezen omdat je hierbij meer moet nadenken en onthouden als je even snel de code moet lezen.
uiteraard is dit een voorbeeld aangezien de functienamen natuurlijk ook niet echt mee werken

Voorbeeld is misschien wat slecht gekozen. Maar ik vind het handig om soms complexe expressies (met veel chaining) op te breken in een aantal stappen. Zodat je niet van die write once read never statements krijgt.

[ Voor 4% gewijzigd door Alarmnummer op 22-09-2005 11:38 ]

[Verwijderd]

@curry684

Voor wie is dat commentaar interressant?
- diegene die van je functie gebruik maakt?
- debugger?
- mede ontwikkelaar met welke reden?

[curry684]

@mark platvoet: jij hebt echt nog nooit in een team gewerkt he

[Janoz]

Ikzelf schrijf, zeker bij iets 'ingewikkeldere' methodes eigenlijk eerst mijn commentaar. Hiermee gooi ik eerst voor mezelf het ontwerp neer. Vervolgens schrijf ik de code ertussen. Eventueel voeg ik later nog een paar dingen toe die misschien wat tegen intuitief lijken.

Maar in principe heb je dat commentaar alleen nodig wanneer je daadwerkelijk in die methode zelf aan het werk bent. De beschrijving van functionaliteit moet gewoon duidelijk zijn. Met javadoc gaat dat gelukkig lekker makkelijk .

[Verwijderd]

curry684 schreef op donderdag 22 september 2005 @ 11:45:
@mark platvoet: jij hebt echt nog nooit in een team gewerkt he

foute aanname.
En tevens een slap argument.

[Verwijderd]

Ik mis nog even het onderscheid tussen commentaar dat het hoe van een blok code beschrijft en commentaar dat het waarom van een blok code beschrijft. Beide zijn (zeker in grote projecten) onontbeerlijk, hoe schoon en duidelijk je code ook is. Maar de tweede categorie ('waarom') wordt nog te vaak overgeslagen.

[Verwijderd]

Annie schreef op donderdag 22 september 2005 @ 11:17:
Waarom moet altijd alles zo zwart-wit zijn?

Ja, natuurlijk moet je duidelijke code schrijven. En ja, het zou mooi zijn als de code self-documenting is. Maar in plaats van als een slechtziende mol met oogkleppen op maar roepen dat je daarom geen commentaar hoeft in te voegen, vind ik weer wat te ver gaan. Schrijven van commentaar is een middel om code duidelijk(er) te maken. Geen doel. Dus waarom zou je dat middel niet gebruiken op de juiste momenten?

Oh, en refactoren is leuk. Maar je kan niet verwachten dat er altijd maar tijd is om code (weer) te herschrijven. Dan kan een enkel regeltje commentaar alles zoveel simpeler maken.

Ja, zo dus!
/me schudt Annie de hand

[Erkens]

Alarmnummer schreef op donderdag 22 september 2005 @ 11:38:
Voorbeeld is misschien wat slecht gekozen. Maar ik vind het handig om soms complexe expressies (met veel chaining) op te breken in een aantal stappen. Zodat je niet van die write once read never statements krijgt.

Nee uiteraard was het veel duidelijker geweest als de naamgeving wat beter was.

offtopic:
Aan de andere kant ligt het natuurlijk ook aan mijn geheugen capaciteit, wellicht moet ik er een reepje mem bij prikken

Verwijderd schreef op donderdag 22 september 2005 @ 11:43:
Voor wie is dat commentaar interressant?

voor iedereen die met die code aan de slag moet

[curry684]

Verwijderd schreef op donderdag 22 september 2005 @ 11:43:
@curry684

Voor wie is dat commentaar interressant?
- diegene die van je functie gebruik maakt?
- debugger?
- mede ontwikkelaar met welke reden?

• Mijzelf nu ik 3 jaar later die code teruglees? Denk je echt dat ik een productie van tienduizenden regels per jaar allemaal onthoudt en exact nog weet wat iedere functie doet?
• Een collega die een deadlock tegenkomt en bij het steppen door deze code komt?
• Een collega die een probleem in de threadpool op moet lossen terwijl ik 2 weken op Kreta zit?
• Mijn opvolger die liever niet een compleet nieuwe threadpool gaat schrijven als dat vliegtuig op Kreta tegen een berg vliegt?
• etc. etc.

Dude, ik wil echt niet weten in wat voor bedrijven en teams je hebt gewerkt als je echt gewoon botweg niet snapt wat het nut is van commentaar. Dat je een stukje PHP gaat herschrijven als je voorganger te lam was om te commentariseren whatever, maar denk je echt dat React morgen unmaintainable is als chem tegen een boom knalt? Of verwacht je dat de volgende developer echt 6 maanden in de code gaat duiken om alles perfect te snappen?!?

[Alarmnummer]

Janoz schreef op donderdag 22 september 2005 @ 11:45:
Ikzelf schrijf, zeker bij iets 'ingewikkeldere' methodes eigenlijk eerst mijn commentaar. Hiermee gooi ik eerst voor mezelf het ontwerp neer. Vervolgens schrijf ik de code ertussen. Eventueel voeg ik later nog een paar dingen toe die misschien wat tegen intuitief lijken.

Als we op die toer gaan. De laatste tijd zet ik mijn functies vaak op vanuit unit tests. Dus eerst de unit tests schrijven (en daarmee krijg ik veel beter de kantel punten boven water) en dan de code schrijven waarmee de unit tests 100% werken.

Maar in principe heb je dat commentaar alleen nodig wanneer je daadwerkelijk in die methode zelf aan het werk bent. De beschrijving van functionaliteit moet gewoon duidelijk zijn. Met javadoc gaat dat gelukkig lekker makkelijk .

Ik duik ook regelmatig code in omdat de documentatie niet sluitend genoeg ik of omdat ik aan het debuggen ben (ik struin bv regelmatig door de Hibernate code omdat er weer iets mis gaat).

[mulder]

Vaak genoeg heb ik eerst comment en dan pas de code. Code zonder comment is als een stratenboek zonder straatnamen.

[Alarmnummer]

Annie schreef op donderdag 22 september 2005 @ 11:17:
Waarom moet altijd alles zo zwart-wit zijn?
Oh, en refactoren is leuk. Maar je kan niet verwachten dat er altijd maar tijd is om code (weer) te herschrijven. Dan kan een enkel regeltje commentaar alles zoveel simpeler maken.

Voor een 'extract to method' hoef je niet veel te doen. De meeste ide`s hebben dit standaard. Dus een regel commentaar of een extract-method gaat denk ik eventueel tijd kosten.

[edit]
Ik ga trouwens van java uit. Ik kan me voorstellen dat dit bij PHP een stuk complexer is (vanwege het dynamische karakter van de taal) en hiervoor geen ondersteuning in een ide zit.

[ Voor 20% gewijzigd door Alarmnummer op 22-09-2005 11:57 ]

[Rac-On]

java moet je ook commenten. Wat je namelijk sommige comment-is-slecht mensen ziet doen, is alles in functies stoppen, en dan krijg je dit soort dingen:

PHP:

function tel-a-bij-b-op(int a, int b){
 return a + b;
}

kijk gewoon ff naar Curry's post, die legt precies uit waarom comment handig is. Je krijgt code helaas simpelweg niet zo dat hij volledig duidelijk is. Dat lukt misschien tijdens informatica op de middelbare school of het eerste jaar uni, maar met grotere projecten echt niet meer

[ Voor 39% gewijzigd door Rac-On op 22-09-2005 12:02 ]

[Verwijderd]

Hee volgens mij is hier een apart topic van gemaakt, want net stond dit allemaal nog in een ander topic??

Maargoed mijn mening:

Wel comments gebruiken. MAAR alleen bij diepgeneste structuren etc, ik heb ook een ex-collega en die deed het dus zo en dat vindt ik fout:

PHP:

for( $i=0; $i <= $m_nNumber; $i++ ) //ga van 0 naar het hoogste
{
}

Dat vindt ik dus echt overbodig, een programmeer zou moeten weten dat hij 0 tot en met een bepaald aantal door loopt, en als je een goede variabele gebruikt om het maximum te bepalen zie je ook meteen waar het mee te maken heeft.

Ik heb weleens een programmaatje gedownload, hete code counter ofzo en daarmee kon je zien hoeveel % van je code comments zijn bij mij was dat 18% vindt ik een redelijk percentage (getest met 2000 regels)

Comments helemaal vermijden vindt ik zowiezo fout, waarschijnlijk als je een beetje overzichtelijke coder bent is je code wel duidelijk en begrijpbaar, maar ik heb liever dat ik even aan de comments kan lezen wat de input is en wat de output is van bijvoorbeeld een bepaalde functie dan de hele code door te nemen en in mijn hoofd uit zitten rekenen wat de output zou kunnen zijn.

Ook als ik commentaar type do ik dat in 9 van de 10 gevallen in het engels. Mijn collega's vinden dat fout (accepteren het wel) maar ik absoluut niet. Ik denk dat vrijwel elke programmeur overweg kan met Engels en daarom als het bedrijf waar ik werk misschien ooit internationaal zou gaan zouden er ook misschien internationale programmeurs zijn. Als je dan je commentaar en en variabelen en functies in het nederlands zou hebben (5000 tot 10.000 regels bijvoorbeeld) zou dit toch wel erg een kritisch tegenpunt zijn vindt.

Zo dit was mijn input

[curry684]

Verwijderd schreef op donderdag 22 september 2005 @ 12:05:
Hee volgens mij is hier een apart topic van gemaakt, want net stond dit allemaal nog in een ander topic??

Maargoed mijn mening:

Wel comments gebruiken. MAAR alleen bij diepgeneste structuren etc, ik heb ook een ex-collega en die deed het dus zo en dat vindt ik fout:

PHP:

for( $i=0; $i <= $m_nNumber; $i++ ) //ga van 0 naar het hoogste
{
}

Dat vindt ik dus echt overbodig, een programmeer zou moeten weten dat hij 0 tot en met een bepaald aantal door loopt, en als je een goede variabele gebruikt om het maximum te bepalen zie je ook meteen waar het mee te maken heeft.

Dat is idd idioot commentaar dat wellicht zoveel ruis oplevert dat de comments als geheel nutteloos worden. Commentaar is niet om basale language constructs te verklaren, maar om de functionele gang van je code te beschrijven naast de technische code zelf.

Correct zou bijvoorbeeld wel zijn:

PHP:

// Create page index by looping over all numbers
for( $i=0; $i <= $m_nNumber; $i++ )
{
}

En idd, Nederlands commentaar is kortzichtig. Ik heb in een all-Dutch bedrijf gezeten hoor waar 2 freelancers uit Engeland bij kwamen. Leg het maar eens uit dan.

[Verwijderd]

Já hoor, commenten is evil?! Straks gaat men nog roepen dat while-lussen moeten vervangen worden door goto's, dat procedureel programmeren veel overzichtelijker is dan object-georienteerd programmeren en dat we voortaan alles in assembler gaan maken!

"Comments plaatsen waar nodig" ís gewoon een criteria dat de meeste bedrijven hanteren als ze programmeurs aannemen. Er zijn zat situaties te bedenken waarin comments gewoon nodig zijn.

Bijvoorbeeld:
- Een API schrijver kan bepaalde terminologie gebruiken die de gebruiker van de API misschien niet direct begrijpt. Dit terwijl die terminologie logisch is in zijn context. Ik denk bijvoorbeeld aan een member als "SetMipmapBias".
- De uitleg waarom je een systeem op een bepaalde manier implementeert en niet anders. (zodat andere programmeurs later de fout niet gaan maken door een ander systeem te gaan implementeren)
- De uitleg waarom je code in een bepaalde volgorde moet uitvoeren. Bepaalde objecten kunnen van elkaar afhankelijk zijn, waardoor deze eerder moeten bestaan. Dit is soms enkel te zien vanbinnen in de klasse en niet bij de aanroep of constructie ervan.
- Ingewikkelde berekeningen kan je niet altijd van self-commenting voorzien. Daarom is het handig om uit te leggen wat de stappen doen in je berekening.

[ Voor 17% gewijzigd door Verwijderd op 22-09-2005 12:42 ]

[RedRose]

Alarmnummer schreef op donderdag 22 september 2005 @ 11:13:
Ik ben zo nu en dan met redelijk complexe meuk bezig: asynchrone communicatie -> threading/channels, prolog compilers en searchengines. Ik heb persoonlijk vaak veel meer aan documentatie op een hoger nivo. Hoe gaat iedereen hier mee om? Zelfs commentaar op class nivo is eigelijk nog vrij nutteloos als het totaal plaatje mist. Volgens mij is deze discussie een stuk interessanter.

Ik zie dat als het verschil tussen strategie en tactiek bij het documenteren en commentaar plaatsen. Bij strategie heb je meer het gehele plaatje met je uiteindelijk te bereiken doelstellingen. De documentatie daarvan houdt niet op met een enkele javadoc. Daar kan je ook een Functioneel ontwerp, Technisch ontwerp, UML-schema's, ERD, javadoc (of whatever ).

Tactiek is meer het nuttig plaatsen van commentaar in methoden of andere stukken code. Ik ga in deze dan ook met Annie en curry684 mee. Als ik code van 3 jaar terug snel weer wil doorhebben of code laat zien aan anderen, dan scheelt het niet alleen veel tijd door goede comments te plaatsen anderen en mezelf snel inzicht te geven, maar het kan ook zeker meer duidelijkheid geven in sommige codeblokken.

Bijvoorbeeld: ik ben nu bezig met de implementatie van een softwarepakket. In dat pakket kan je stukken includen aan de hand van een identifier:

code:

#include "10-239-32"

Als ik hier geen comment bijplaats, dan kan ik een uur zoeken tussen de tientallen includeblokken om er achter te komen wat ik nou eigenlijk include. Daarnaast is het ook wel nuttig voor anderen (we werken in een team) om te zien wat er wordt geincluded.

Verder: éénregelig commentaar bij kleine codestukken, a la: '// Create page index by looping over all numbers' vind ik noodzakelijk om een goed beeld te hebben.

[ Voor 3% gewijzigd door RedRose op 22-09-2005 12:47 . Reden: verduidelijking ;) ]

[whoami]

Verwijderd schreef op donderdag 22 september 2005 @ 11:43:
@curry684

Voor wie is dat commentaar interressant?
- diegene die van je functie gebruik maakt?
- debugger?
- mede ontwikkelaar met welke reden?

Voor diegene die van de functie gebruik maakt, kan het commentaar die beschrijft wat de functie doet, heel handig zijn.
Voor een mede-ontwikkelaar kan het ook interessant zijn, om bv een bug op te sporen, of als hij jouw code 'erft'.
Voor jezelf kan het ook interessant zijn, als je na x maanden / jaren diezelfde code moet herbekijken.

[Michali]

Ik ben ook absoluut niet tegen commentaar. In het voorbeeld wat ik echter gaf was het gedeelte zo duidelijk een aparte taak dat het imo het beste is om die dan te verplaatsen naar een aparte functie. Dat is ook een goed teken dat een 'extract method' uit te voeren is. Als een code blok te complex is om gemakkelijk en begrijpelijk te lezen, maar wel echt samenhoort met andere code (dus deel is van een bepaalde operatie/actie) en geen actie is op zichzelf, dan is het imo ook niet goed om er dan een aparte functie van te maken. Een functie moet echt een op zichzelf staande taak zijn (in de meeste gevallen, je hebt natuurlijk altijd uitzonderingen), welke dudelijk omschreven wordt door zijn naam. Als je een code blok (wat eigenlijk een duidelijk een aparte handeling is) gaat omschrijven om zijn taak, zonder dat het in een functie blok staat, dan ben je imo ook fout bezig. De grens is soms mischien een beetje moelijk te vinden, maar ik denk dat het wel redelijk snel te identificeren is.

Bijvoorbeeld als je een regel commentaar hebt die niet alleen slaat op 1 enkel blokje code, maar ook op enkele die daarna komen. Dat betekent dus dat enkele code blokken gezamelijk een actie of handeling vormen. Imo is dat dan wel een goed idee om die blokken te verplaatsen naar een aparte functie (die dan wel gedocumenteerd dient te worden mbv. commentaar).

Het allerbelangrijkst is dat je duidelijk en gestructureerd programeert, naar mijn mening. Dat je dus duidelijk namen gebruikt voor functies en variabelen die de intentie ervan onthullen en duidelijk maken. Ook conventie is erg belangrijk. Dat je dus (met je team) een bepaalde manier van werken afspreekt (een bepaalde notatie wijze voor constanten, variabelen en classes etc.). Daarnaast moeten sommige zaken (waar dan nog niet in 1 oogopslag duidelijk is wat de intentie en bedoeling is) dan van commentaar worden voorzien. Als je dat niet doet ben je ook fout bezig.

Zijn er trouwens ook mensen die aan "Pseudocode Programming Process" doen? Dus dat je eerst puur je intentie uitschrijft voor een stukje code, dan na iedere regel één of enkele regels code toevoegt die de omschrijving van de regel waarmaken, en dan van alle pseudocode commentaar maken. Dat imo een erg goede manier om te werken. Ten eerste ben je eerst puur met je intentie bezig. Je denkt er dan beter over na (ook door het in woorden te proberen uit te drukken). Daarna is het programmeer werk ook een stuk gemakkelijker, omdat je eigenlijk al weet wat je wilt doen. Laatste voordeel is dat je geen commentaar achteraf hoeft toe te voegen en dat de comments exact beschrijven wat je intentie is. Zelf pas ik het nog niet zo toe, maar ik wil er wel wat meer mee experimenteren. (Dit process staat trouwens beschreven in het boek Code Complete).

[Annie]

Michali schreef op donderdag 22 september 2005 @ 13:04:
Zijn er trouwens ook mensen die aan "Pseudocode Programming Process" doen? Dus dat je eerst puur je intentie uitschrijft voor een stukje code, dan na iedere regel één of enkele regels code toevoegt die de omschrijving van de regel waarmaken, en dan van alle pseudocode commentaar maken.

Iets dergelijks doe ik inderdaad al wel vaak. Ik schrijf vaak eerst in korte stukjes commentaar wat ik wil gaan doen (en/of waarom ik dat zo wil doen). Daarna voeg ik de daadwerkelijke code pas toe.

Daarmee sla ik 2 vliegen in 1 klap:
[list]
• ik heb m'n commentaar eigenlijk al zo goed als klaar;
• ik ben na de implementatie van het eerste stukje niet vergeten hoe ik de rest van de code wilde aanpakken.

[Verwijderd]

Tsja je kunt ook test driven development toepassen, dat is praktisch hetzelfde alleen staat er direct een solide test.

[Michali]

Verwijderd schreef op donderdag 22 september 2005 @ 13:36:
Tsja je kunt ook test driven development toepassen, dat is praktisch hetzelfde alleen staat er direct een solide test.

Het testen van een stuk code heeft echt niets te maken met je intentie. Bij testen probeer je gewoon uit of een functie het afgesproken contract wel nakomt. Comments toevoegen zeggen leggen juist wat je intentie is bij een bepaalde handeling. Ik denk niet dat je de twee elkaar uitschakelen. Ze zijn beide nodig.

[Verwijderd]

Dat doe je bij test driven development ook. Je legt immers de contracten vast in je test alvorens je de implementatie schrijft.

[Alarmnummer]

Maar blijft de discussie op dit nivo door gaan? Wel of geen ge-extracte method vind ik van buitenaf gezien niet veel uitmaken. De scope van de oplossing blijft beperkt tot de class en is daarom niet echt super interessant. Iedereen is het eens dat documentatie op method/class nivo noodzaak is..

[pjonk]

Veel heb ik hier niet aan toe te voegen, maar naast code documentatie zijn functionele beschrijvingen en technische specificaties ook geen overbodige luxe. Je wilt niet in de code en comments gaan graven om uit te zoeken hoe iets ook alweer werkt.

[Rac-On]

test driven development werkt alleen als je eerst een functionele specificatie maakt en daarna door iemand anders tests laat bouwen. Anders ben je bezig een oplossing voor je test te maken, ipv je functionele specificatie te volgen.

Ik programmeer zelf nagenoeg alleen maar via de pseudo-code manier. Werkt heerlijk, duidelijk en overzichtelijk. Ook kan je door al die commentaar regeltjes makkelijk zien hoever je al bent en wat je nog moet doen

[MMUilwijk]

Ik ben werkzaam als docent Bedrijfskundige Informatica (HBO) en ik eis van mijn studenten (1e t/m 4e jaars) dat ze op een nette manier coderen. Te vaak ben ik projecten tegengekomen waarvan ik de code moest beoordelen en dan zonder commentaar een paar duizend regels code mocht gaan doorspitten. Dat is dan dus linea recta terug naar de student met die zult.

Daarnaast kan het voor studenten een stuk eenvoudiger zijn om een applicatie te bouwen wanneer ze eerst in commentaar de pseudo code hebben doorlopen, de logica is dan immers al bedacht. Vaak komt een studenten dan tot een "stappenplan" en is het nog een kwestie van de juiste syntax.

Ik ben wel van mening dat duidelijke naamgeving van essentieel belang is. Ook daar wordt door ons streng op gelet, geen loze variabele namen.

Kortom, geen commentaar is dodelijk en pseudo-code helpt enorm bij het ontwerpen van code en het plaatsen van de juiste logica.

[curry684]

Real Programmers don't comment their code. If it was hard to write, it should be hard to understand.

[.oisyn]

Verwijderd schreef op donderdag 22 september 2005 @ 10:34:
Ja en dat is leesbaar. hierboven staat ook een mooi voorbeeld in php van hoe het moet.
Probeer het nou eens, probeer nou eens in te denken dat je code gewoon slecht is als het commentaar behoeft.

Nee, haal jij nou eens die enorme plaat voor je kop weg en besef eens dat niet alle code hetzelfde is. Jij hebt overduidelijk nog nooit ingewikkelde code geschreven. Laat me raden, je maakt websites, database of business applications? Niets mis mee hoor, maar er komen nou ook niet echt vaak bepaald complexe implementaties in voor.

Op het moment dat je wat complexere algoritmes gaat ontwerpen, die je eerst op papier uitwerkt, zijn die comments van levensbelang omdat je anders de volgende week (!!!) al niet meer weet wat de code precies doet, en dat is nogal vervelend als er ergens een bug in blijkt te zitten. En nee, die dingen zijn niet altijd mooi te unittesten, veel algoritmes vereisen een grafische visualisatie en een controle door een mens om te kijken of het klopt.

Zo ben ik momenteel toevallig bezig met culling algoritmes voor onze nieuwe 3d engine, en daar komt nogal wat bij kijken, zoals intersectiontests tussen paren uit de set { bollen, boxes, cyllinders, kegels, frusta }. Mag jij mij eens uitleggen waarom dit werkt (expres zonder comments):

C++:

bool Intersects(const CullingSphere & a, const CullingCone & b)
{
    Vector3 aOrig = a.Origin() - b.Origin();
    float32 f = aOrig * b.Dir();
    if (f >= b.Height())
    {
        aOrig -= b.Dir() * b.Height();
        float32 minDist = a.Radius() + b.Radius();
        return aOrig.LenSquared() < minDist * minDist;
    }

    if (f < -a.Radius())
        return false;

    float d = Sqrt(b.Radius()*b.Radius() + b.Height()*b.Height());
    float minDist = (d * a.Radius() + f * b.Radius()) / b.Height();
    Vector3 aOrigF = aOrig - f * b.Dir();
    if (aOrigF.LenSquared() >= minDist * minDist)
        return false;

    float y = a.Radius() * b.Radius() / d;
    if (f > -y)
        return true;

    return aOrig.LenSquared() < a.Radius() * a.Radius();
}

Of nog erger: ga de bug opsporen als het niet werkt. Zelf documenterende code werkt niet altijd, de belangrijkste comments vind ikzelf ook niet eens zozeer wat de code precies doet, maar waarom jij die keuze gemaakt hebt, want dát is niet aan de code af te lezen.

[Woudloper]

Naast het gewoon commentaar geven in je code is het naar mijn mening ook altijd erg belangrijk om aan te geven (bij het doen van changes) welke stuk van te code is aangepast ten gevolgende van die en die change. Wij doen dat dan meestel door een combinatie van je initialen, datum en het issuenummer.

[.oisyn]

Woudloper: daar heb je toch sourcecontrol voor?

[Verwijderd]

@.oisyn
jij vraagt me nu 'slechte' code (lees: slechte naamgeving) te verklaren, waarom zou ik dat moeten doen? Het gaat er juist om dat het niet nodig zou zijn als je code gewoon duidelijke attribuut en functie namen heeft en er een degelijke flow op na houd.

Verder stoor ik me behoorlijk aan het feit dat als iemand een andere mening heeft het gelijk over de boeg van ervaring wordt gegooid, een kwalijke eigenschap van velen hier. Het voegt niets toe. Het toont enkel je eigen onkunde.

[Zoijar]

Of dit soort code, ik zet soms wel bij elke regel commentaar.

C++:

void Compression::compress(uint32 passes, uint32 dictfrac, float quality, uint32 transform_levels, const DataLayout& data) {
    t_ = Wavelet(transform_levels);
    
    // Set the data location and strides etc
    t_.setData(data);

    // Perform the wavelet transform
    t_.transform();

    // Set the threshold automatically
    t_.setUniversalThreshold();

    // Array to hold the thresholded wavelet bands
    bands_ = new Wavelet::Band[transform_levels+1];

    // Threshold all bands, and store them in a lossy dictionary
    uint32 totalsig = 0;
    double totallost = 0;
    
    // Threshold and quantize
    for (uint32 i=0; i<=transform_levels; ++i) {
        uint32 largestKey = 0;
        bands_[i].invq = t_.quantizedSubband(i, bands_[i].ar, LossyDictionary::data_bits, largestKey);

        // Sort coefficients on abs value, so larger values have higher chance of being stored
        bands_[i].ar.quicksort();

        // Remove 1-quality percentage of smallest wavelet coefficients
        bands_[i].ar.truncate(static_cast<int>(bands_[i].ar.size()*quality));

        // Table size equal to nr of sig components, key/index space of largest key size
        // round up to size divisible by 2. Minimum size is 2.
        uint32 dictsize = std::max<uint32>(2, (((bands_[i].ar.size()*dictfrac/100))+1)&~1);

        // Keep statistic on significant coefficients
        totalsig += bands_[i].ar.size();

        // Store the keyset in the dictionary. Returns the number of coefficients lost
        bands_[i].dict = new PTRS::LossyDictionary(dictsize, largestKey+1);
        totallost += bands_[i].dict->hashKeyset(bands_[i].ar, passes);

        // Free mem of array
        bands_[i].ar.erase();
    }
}

Zonder het commentaar had je echt niet precies geweten wat er gebeurt na een tijdje. Waarom doe je die quicksort() bv? Code zonder commentaar kan je vaak wel lezen, maar niet goed begrijpen. Je vraagt jezelf vaak af "waarom doen ze dit?". Je snapt wel wat ze doen, maar niet waarom. Waarom is het nodig om je coefficienten te sorteren?

Haha, of deze code zonder commentaar...

C++:

unsigned int ZCurveMapPolicy::cartesianToZCurve(const Index& ci) const {
// guard against special edge case
    if (!(ci.x() == static_cast<int>(edge_length_)-1 || ci.y() == static_cast<int>(edge_length_)-1)) {
        // The (global) Z-index of ci, j, divided by 2^l where l is the level
        // round down to an even number, or the number itself if it was even.
        // this maps from global hi-res Z-index to local lower-res Z-index
        unsigned int j = bitInterleave(ci.x(), ci.y());
        unsigned int bc = std::min<unsigned int>(countTrailingZeros(j | (1<<31))<<1, max_level_);
        unsigned int level = (bc) + (((j>>bc)&3)==3);
        j >>= (level&0xFFFFFFFE);

        // j>>2 is the number of times we go through a 'Z'
        // Every time this happens, we have to skip some indices. So we sub this from j.
        // On even levels we have to skip 2, on odd ones we have to skip 3
        // On even we start at offset 1, on odd we start at offset 3
        // The hierarchical shift is done like this so it will work when max_level_-level=0
        return j                                // The low-res z-index
               - ((j>>2)*((level&1)+2))         // Z-curves passed times 1 or 2
               - (((level&1)*2)+1)              // start at 3 or 1
               + (level == max_level_)          // special case when level is max, we dont have to sub 1
               + ((1<<(max_level_-level))>>1);  // add hierarchical offset
    }
    else if (ci.y() == static_cast<int>(edge_length_)-1) {
    // We're on the bottom row
        return ci.x()                               // The low-res z-index
               + (1<<max_level_);   // add hierarchical offset

    } else {
    // We're on the right most column
        return ci.y()
               + (1<<max_level_)+edge_length_;
    }
}

Code kan vaak gewoon niet simpeler... Zelfs als de code voor zichzelf spreekt, aosl min of meer in het bovenste vorbeeld, dan nog wil je weten waarom. In het laatste voorbeeld zie je denk ik ook wel dat het onmisbaar is. Toegegeven je zou dat oip kunne pslitsen, maar dan wordt het langzaam...

[Erkens]

Verwijderd schreef op donderdag 22 september 2005 @ 16:09:
@.oisyn
jij vraagt me nu 'slechte' code (lees: slechte naamgeving) te verklaren, waarom zou ik dat moeten doen? Het gaat er juist om dat het niet nodig zou zijn als je code gewoon duidelijke attribuut en functie namen heeft en er een degelijke flow op na houd.

de naamgeving in dat voorbeeld is redelijk goed, je kan natuurlijk ook overdrijven en hele verhalen schrijven in de naam van de variabele, maar of het daar nu veel duidelijker van wordt

Verder stoor ik me behoorlijk aan het feit dat als iemand een andere mening heeft het gelijk over de boeg van ervaring wordt gegooid, een kwalijke eigenschap van velen hier. Het voegt niets toe. Het toont enkel je eigen onkunde.

Geef zelf dan een real life voorbeeld

[Rac-On]

precies, gezien je leeftijd lijkt het me onwaarschijnlijk dat je, zoals .oisyn al aangeeft, ooit aan serieus grote projecten hebt gewerkt. Jouw mening is volgens mij gebasseerd op:
- ervaring met je eigen hobby-projecten
- wat je in 6 vwo/ 1ste jaar uni hebt geleerd
- dingen die je gelezen hebt

maar zeker niet op real-life ervaring. Wat jij beschrijft, zelf documenterende code, werkt nog wel voor een simpele website, maar niet voor projecten van duizenden, zo niet miljoenen regels code waar je met een man of 5 tegelijk aan aan het werken bent. Of functies waarbij je 3 dagen met z'n 2'en zit te denken en schetsen te maken voordat je in psuedo code hebt bedacht wat je gaat doen.

[.oisyn]

Verwijderd schreef op donderdag 22 september 2005 @ 16:09:
@.oisyn
jij vraagt me nu 'slechte' code (lees: slechte naamgeving) te verklaren, waarom zou ik dat moeten doen?

Het feit dat je het gooit op slechte naamgeving zegt al genoeg . Al maak ik er een sprookje van dan nog kun je niet beschrijven wat ik nou eigenlijk aan het doen ben hier. En daarmee probeer ik niemand's incompetentie mee aan te tonen overigens, ikzelf zou ook niet begrijpen wat ik aan het doen ben als ik dat stukje code zie, dat snap ik pas als ik de daadwerkelijke comments lees waar bovendien een referentie in staat naar een ingescande tekening die ik destijds heb gemaakt

Verder stoor ik me behoorlijk aan het feit dat als iemand een andere mening heeft het gelijk over de boeg van ervaring wordt gegooid, een kwalijke eigenschap van velen hier. Het voegt niets toe. Het toont enkel je eigen onkunde.

Lol, maar mark, heb je niet juist ervaring nodig om een goede mening aan te meten? Heb je niet juist ervaring nodig om aan te tonen dat een kortzichtige visie niet altijd hoeft te gelden voor alle gevallen? Het feit dat jij denkt dat _alle_ code zelfbeschrijvend kán zijn geeft alleen maar aan hoe kortzichtig die visie is, en dat toon ik aan dmv argumenten en een voorbeeld. Nogal kinderachtig om dan maar te zeggen dat ik het dan gooi op ervaring, ipv proberen open te staan voor de argumenten die gegeven worden. Maar goed, jouw wil is blijkbaar wet en van mensen met meer ervaring (volgens je eigen zeggen) wil je niets horen, waarom doe je dan nog überhaupt mee met discussies? Ga anders op tweakzone vertoeven ofzo, daar kun je nog fijn heer en meester zijn (in het land der blinden is éénoog koning immers)

Overigens ga je ook echt alleen maar in op het voorbeeld, de rest wat ik zeg negeer je voor het gemak maar even (met name de laatste regel, die Zoijar hierboven ook nog eens mooi demonstreert)

[ Voor 16% gewijzigd door .oisyn op 22-09-2005 16:33 ]

[Nick The Heazk]

"Goede code heb je als elke programmeur zonder voorkennis van de taal jouw code begrijpt"

Dat is voor mezelf de definitie van goede code. Dat houdt netjes schrijven, logische naamgeving, gestructureerd werken en goede comments in.

Ik beschrijf wat de functies doen, wat ze retourneren (en eventueel aan wie ze dat doen) en wat er bij errors gebeurt.

Ik heb echter nog nooit in team gewerkt maar ik realiseer me dat goede commenting essentiëel is, wil je de code snel doornemen. Voorbeelden op tweakers te over

[Verwijderd]

edit
nevermind

ik wil het ook eigelijk niet eens meer weten.

[ Voor 85% gewijzigd door Verwijderd op 22-09-2005 16:34 ]

[Zoijar]

rac-on schreef op donderdag 22 september 2005 @ 16:20:
Jouw mening is volgens mij gebasseerd op:
- wat je in 6 vwo/ 1ste jaar uni hebt geleerd

Als je op je eerste uni jaar code zonder commentaar inlevert, dan blijft het ook bij je eerste uni jaar...

[Rac-On]

Zoijar schreef op donderdag 22 september 2005 @ 16:32:
[...]

Als je op je eerste uni jaar code zonder commentaar inlevert, dan blijft het ook bij je eerste uni jaar...

geen idee, ben na een half jaar gestopt
ik moet trouwens zeggen dat jouw voorbeeld op sommige punten wel wat overdone vindt:

PHP:

    // Set the data location and strides etc 
    t_.setData(data); 

    // Perform the wavelet transform 
    t_.transform(); 

    // Set the threshold automatically 
    t_.setUniversalThreshold();

misschien ietswat te voor de hand liggend om daar comments bij neer te zetten

[Zoijar]

rac-on schreef op donderdag 22 september 2005 @ 16:37:
geen idee, ben na een half jaar gestopt

Jammer. Of verstandig. Misschien had ik dat ook moeten doen Anyway, off-topic

ik moet trouwens zeggen dat jouw voorbeeld op sommige punten wel wat overdone vindt:
misschien ietswat te voor de hand liggend om daar comments bij neer te zetten

Mwja. Dat zou men kunnen denken idd. Maar ik vind het handig als elk logisch blokje een regel commentaar bevat met wat (waarom) het doet. Ik lees het liefst door regels commentaar heen om te zien wat iets doet; even snel door alle regels en je weet het "ohja, zet de data...doe je transform, en bereken een automatische threshold, oh ok dat hoeven we dus niet zelf te doen." Hoef ook niet op te zoeken wat die methoden precies doen, het idee is duidelijk.

Ik denk dat je hetzelfde idee bij deze code hebt dan:

C++:

/* Recursively copy a "level" indirect block with source blocknumber "block_nr"
 * to the destination as a sequence of consecutive blocks.
 */
zone_t copy_block(zone_t block_nr, unsigned int level) {
   register int i;

   /* Destination block is the next free data block */
   zone_t dst_block = dst_super.s_firstdatazone + blocks_written;

   /* Check if the block is in-use; if not the input fs is inconsistent */
   if (!TST_BIT(src_z_map, block_nr-src_super.s_firstdatazone+1)) {
      exit_error(6, "Input filesystem inconsistency (run fsck)");
   }

   /* Read the diskblock into the right buffer */
   read_block_n(src_fd, block_nr, (char*)(block_buf[level]));

   /* Skip one block on destination, we will write the block here later */
   blocks_written++;

   /* Flag the block as in-use in the destination zonemap */
   SET_BIT(dst_z_map, blocks_written);

   /* Test if we need to recurse, or that this is a direct (level 0) block */
   if (level > 0) {
      for (i=0; i<V2_INDIRECTS; ++i) {
         if (block_buf[level][i] != NO_ZONE) {
            /* Recurse to lower level */
            block_buf[level][i] = copy_block(block_buf[level][i], level-1);
         }
      }
   }

   /* Write the block and return the block number it was written to */
   write_block_n(dst_fd, dst_block, (const char*)(block_buf[level])); 
   return dst_block;
}

Maar bv de regel

C++:

/* Skip one block on destination, we will write the block here later */
   blocks_written++;

is voor mij onmisbaar. Zonder die regel moet je zoeken "heh, wat gebeurt er dan met dat block? die wordt nu niet weggeschreven? zoeken... oh, ok dat gebeurt later in functie xxx" Hetzelfde geldt voor die andere regels. Ik vind het persoonlijk niet fijn als ik code moet begrijpen om te zien wat iets doet, of als ik naar andere code moet terug zoeken... Hoewel ik niet altijd zo'n heilige ben als in deze voorbeelden hoor. In code in ontwikkeling zet ik niet zoveel neer, omdat het nog zo vaak veranderd. Dan begin ik met de echt vage en nodige dingen te documenteren, zoals "Don't forget to increment this! Else it will loop indefinitely". Als ik de code dan later om gooi weet ik dat nog. Maar uiteindelijk als het 'af' is (voordat je het inchecked), dan loop ik het nog even door en zet ik overal iets bij. Ik heb er net mee gewerkt, voor mij is het makkelijk om te doen, alles zit in mijn hoofd. Meer commentaar kan nooit kwaad.

[Verwijderd]

.oisyn schreef op donderdag 22 september 2005 @ 16:22:
Lol, maar mark, heb je niet juist ervaring nodig om een goede mening aan te meten? Heb je niet juist ervaring nodig om aan te tonen dat een kortzichtige visie niet altijd hoeft te gelden voor alle gevallen? Het feit dat jij denkt dat _alle_ code zelfbeschrijvend kán zijn geeft alleen maar aan hoe kortzichtig die visie is, en dat toon ik aan dmv argumenten en een voorbeeld.

Wat een ongegronde bullshit. Tuurlijk heb je ervaring nodig om een standpunt in te nemen. Maar het is kwalijk dat gebrekkige ervaring een argument moet zijn om je gelijk te halen, en dat is wat er gebeurd. Die ervaring zou zich beter kunnen uiten in een degelijk voorbeeld waar commentaar essentieel is. Maar die blijven helaas uit. Zodoende blijf ik van mening dat code geen commentaar behoeft (dit betreft niet klasse of methode documentatie). Uiteraard zal er ergens een uitzondering zijn te vinden maar dat mag niet interressant genoemt worden in een algemene discussie. En dan vergeet ik bij deze wederom weer dat "gebash".

[NMe]

Verwijderd schreef op donderdag 22 september 2005 @ 16:31:
edit
nevermind

ik wil het ook eigelijk niet eens meer weten.

Toch grappig eigenlijk dat je in de post die hier eerst stond weer reageerde op iemand die je persoonlijk aanviel, maar niet reageert op een inhoudelijke reactie. Je bent je op dit moment sowieso aan het verdedigen, dat snap ik. Maar gaat dat je niet beter af als je inhoudelijke argumenten van anderen probeert te weerleggen met inhoudelijke argumenten van jezelf?

Zoals hierboven al gezegd: leesbare code maken zonder oneliner-comments is een utopie, al was het alleen maar omdat je in code geen intentie en gevolgtrekking kunt opnemen. Met naamgeving kun je aangeven wat je doet en eventueel hoe maar niet waarom.

Verwijderd schreef op donderdag 22 september 2005 @ 17:02:
Die ervaring zou zich beter kunnen uiten in een degelijk voorbeeld waar commentaar essentieel is. Maar die blijven helaas uit.

Was dat voorbeeld van .oisyn dan geen voorbeeld waar commentaar essentiëel is? Of die twee van Zoijar hierboven? Maar nee, jij vindt dat die code van .oisyn last heeft van slechte naamgeving. Nou, dan nodig ik je uit om een voorbeeld van jouw code te posten die zo goed is dat er geen commentaar bij hoeft.

[ Voor 26% gewijzigd door NMe op 22-09-2005 17:05 ]

[Verwijderd]

-NMe- schreef op donderdag 22 september 2005 @ 17:02:
Was dat voorbeeld van .oisyn dan geen voorbeeld waar commentaar essentiëel is? Of die twee van Zoijar hierboven? Maar nee, jij vindt dat die code van .oisyn last heeft van slechte naamgeving.

Ja en terecht: "src_fd".

[NMe]

Verwijderd schreef op donderdag 22 september 2005 @ 17:08:
Ja en terecht: "src_fd".

Wauw, één dingetje dat onduidelijk is! (En dan sowieso in Zoijar's code, en niet in die van .oisyn waar ik voornamelijk op doelde, want die beschuldigde je specifiek van "slechte naamgeving".)

Nogmaals: laat dan eens wat van jouw code zien. Jij zegt dat je die Utopie hebt waargemaakt dat iedereen die je code leest het meteen begrijpt. Dan zou ik dat graag eens willen zien.

[ Voor 17% gewijzigd door NMe op 22-09-2005 17:11 ]

[Alarmnummer]

Verwijderd schreef op donderdag 22 september 2005 @ 17:02:
[...]
Wat een ongegronde bullshit. Tuurlijk heb je ervaring nodig om een standpunt in te nemen. Maar het is kwalijk dat gebrekkige ervaring een argument moet zijn om je gelijk te halen, en dat is wat er gebeurd. Die ervaring zou zich beter kunnen uiten in een degelijk voorbeeld waar commentaar essentieel is.

Volgens mij heb je die genoeg gezien. En verder begrijp ik gewoon niet hoe je zonder commentaar in je code kunt werken. Op het moment dat je voor ieder stuk commentaar een methode gaat maken, hoe ga je dan om me alle ruis in een class van methodes die alleen een betekenis hebben binnen een bepaalde context? Post eens wat random code van je want ik wil wel eens zien hoe dat eruit ziet.

[.oisyn]

Verwijderd schreef op donderdag 22 september 2005 @ 17:02:
Maar het is kwalijk dat gebrekkige ervaring een argument moet zijn om je gelijk te halen, en dat is wat er gebeurd.

Pardon? Quote eens het preciese stuk in mijn post waarin ik het gemis van jouw ervaring als argument gebruik?

Die ervaring zou zich beter kunnen uiten in een degelijk voorbeeld waar commentaar essentieel is. Maar die blijven helaas uit.

Moet je luisteren, de voorbeelden in deze topic zijn legio, maar jij wilt ze gewoon niet zien. Ja sorry, ik kan net zo goed tegen een betonnen muur aan gaan staan praten.

[Verwijderd]

-NMe- schreef op donderdag 22 september 2005 @ 17:10:
Wauw, één dingetje dat onduidelijk is! (En dan sowieso in Zoijar's code, en niet in die van .oisyn waar ik voornamelijk op doelde, want die beschuldigde je specifiek van "slechte naamgeving".)

Ik neem aan dat je begreep dat het domweg het eerste stukje wat ik tegenkwam was toen ik een gooi aan het muiswieltje gaf...

[.oisyn]

En daarnaast -en hoewel dat idd geen argument is- gaat er bij jou geen belletje rinkelen bij het feit dat iedereen hier het met je oneens is? Begin je dan ook maar niet een beetje te twijfelen over je eigen standpunten en dat er wellicht wel een kern van waarheid in zit in wat we zeggen? Of blijf je gewoon stug ontkennen zonder argumenten te weerleggen en zelfs zonder argumenten van jezelf te komen?

Want zoals -NMe- idd al zei, je lijkt juist alleen op die reacties in te gaan waar geen argumenten in staan, zoals je hierboven ook weer mooi aantoont. Is die opmerking van -NMe- die je zojuist gequote hebt interessanter om op te reageren dan de rest van de (imho) valide argumenten die door verschillende mensen zijn aangedragen?


.edit: @ rac-on hieronder me: Dat vermoeden had ik idd ook, ik dacht al dat het aan mij lag maar jij snapt blijkbaar ook wat ik in die post nou exact probeerde te zeggen

[ Voor 42% gewijzigd door .oisyn op 22-09-2005 17:20 ]

[Rac-On]

.oisyn schreef op donderdag 22 september 2005 @ 17:11:
[...]

Pardon? Quote eens het preciese stuk in mijn post waarin ik het gemis van jouw ervaring als argument gebruik?

[...]
Moet je luisteren, de voorbeelden in deze topic zijn legio, maar jij wilt ze gewoon niet zien. Ja sorry, ik kan net zo goed tegen een betonnen muur aan gaan staan praten.

ik denk dat hij het begin van bijv deze message bedoelt: .oisyn in "[alg] Commentaar in code nodig of overbo..."

Wat er hier verward wordt is dat jij denkt dat we zeggen "je hebt geen ervaring, dus je hebt niet gelijk", terwijl we eigenlijk zeggen "je hebt geen ervaring, dus ben je nog nooit voorbeeld X, voorbeeld Y en voorbeeld Z tegengekomen, en wij wel en daarom vinden we dat je niet gelijk hebt"

[ Voor 3% gewijzigd door Rac-On op 22-09-2005 17:16 ]

[NMe]

Verwijderd schreef op donderdag 22 september 2005 @ 17:14:
Ik neem aan dat je begreep dat het domweg het eerste stukje wat ik tegenkwam was toen ik een gooi aan het muiswieltje gaf...

Kap eens met zo selectief zijn in waarop je al dan niet reageert. In diezelfde post die je quote vroeg ik of je dan kan bewijzen dat je deze heilige graal hebt bereikt door een codefragment te laten zien dat iedere fatsoenlijke programmeur meteen begrijpt. In de post van mij daarboven vroeg ik het ook, en ook Alarmnummer stelt die vraag. Je gaat hier niemand overtuigen zonder een beetje bewijs, en met die halstarrige houding van je waarin je jezelf wel verdedigt maar niets fatsoenlijk beargumenteert al zeker niet.

[Mick]

Verwijderd schreef op donderdag 22 september 2005 @ 12:39:
[...] "Comments plaatsen waar nodig" ís gewoon een criteria dat de meeste bedrijven hanteren als ze programmeurs aannemen. Er zijn zat situaties te bedenken waarin comments gewoon nodig zijn. [...]

Eensch. Commentaar plaatsen op plekken waar gewoon obvious is wat er gebeurt is alleen maar irritant ('papegaai-commentaar'), maar er zijn zeker plekken waar het IMO vrijwel altijd moet. Bijvoorbeeld aan het begin van een functie is het goed gebruik om het doel van de functie en de argumenten te verhelderen.

Op de uni werd gesproken van pre- en postcondities die altijd bij iedere functie geplaatst moesten worden, om de toestand van het programma voor en na aanroep te beschrijven. Dat is misschien wat overdreven, soms had je dan het idee dat je dat alleen maar aan het inkloppen was omdat het weglaten ervan minpunten opleverde. Maar een korte statement wat de zin van bepaalde stukjes code is, is zeker handig; ik heb het meerdere malen meegemaakt dat ik een project na een paar weken/maanden weer eens bekeek en alleen dankzij de comments kaas van mijn eigen code kon maken. Terwijl ik tijdens het schrijven nota bene m'n best had gedaan om heldere gestructureerde code te bakken en zoveel mogelijk zelfverklarende functie- en variabele-namen te gebruiken.

[ Voor 3% gewijzigd door Mick op 22-09-2005 17:36 ]

[Verwijderd]

-NMe- schreef op donderdag 22 september 2005 @ 17:18:
Kap eens met zo selectief zijn in waarop je al dan niet reageert. In diezelfde post die je quote vroeg ik of je dan kan bewijzen dat je deze heilige graal hebt bereikt door een codefragment te laten zien dat iedere fatsoenlijke programmeur meteen begrijpt. In de post van mij daarboven vroeg ik het ook, en ook Alarmnummer stelt die vraag. Je gaat hier niemand overtuigen zonder een beetje bewijs, en met die halstarrige houding van je waarin je jezelf wel verdedigt maar niets fatsoenlijk beargumenteert al zeker niet.

Ik heb hier enkel code van mijn werk, dat ik logischerwijs niet ga posten.

[Mick]

Verwijderd schreef op donderdag 22 september 2005 @ 17:36: [...] Ik heb hier enkel code van mijn werk, dat ik logischerwijs niet ga posten.

Met het posten van een illustratief fragment geef je geen bedrijfsgeheimen weg hoor.

[Verwijderd]

Roboticles schreef op donderdag 22 september 2005 @ 17:41:
Met het posten van een illustratief fragment geef je geen bedrijfsgeheimen weg hoor.

Het is geen discussie punt. Dus als ik vanavond in een onverlaten moment de behoefte heb om achter de pc te duiken post ik wel wat van mezelf.

[ Voor 4% gewijzigd door Verwijderd op 22-09-2005 17:45 ]

[RayNbow]

-NMe- schreef op donderdag 22 september 2005 @ 17:18:
In diezelfde post die je quote vroeg ik of je dan kan bewijzen dat je deze heilige graal hebt bereikt door een codefragment te laten zien dat iedere fatsoenlijke programmeur meteen begrijpt.

Java:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

?

Maar goed, nu meer on topic...
Ik houd van commentaar, maar ik kwam laatst achter, dat ~70% van de regels van een bepaalde .c file die ik heb geschreven voor een project commentaar was. De vraag is nu, heb ik te veel commentaar getypt?

[curry684]

70% is wel weer het andere uiterste ja

[Verwijderd]

Mensen, een voorstel van mijn kant:
Volgens mij is mark platvoet van mening dat commentaar in code slecht is, en staat hij niet open voor een andere mening. Veel anderen zjin van mening dat code liefst zo veel mogelijk 'self explanatory' moet zijn, maar waar nodig ook gewoon in de code opgenomen moet worden, en willen mark platvoet daarvan overtuigen. Volgens mij liggen die standpunten niet eens zo ver uit elkaar, maar uit de toon van de discussie lijkt het heel anders en zwart-wit ...

Mijns inziens moet iemand open staan om iets nieuws te leren / te veranderen, en het met z'n allen inbashen dat hij ongelijk heeft zal niets opleveren, dus waarom daarmee doorgaan? Andersom wil mark platvoet kennelijk niet open staan voor andere meningen, dus ik vraag me ook af waarom hij na zijn statements nog reageert.

Los van de inhoud van de discussie is in de beleving van de mens geen universeel goed of fout, alleen maar perceptie vanuit je eigen beleving, so let's agree to disagree en laten we stoppen met dit "ik heb gelijk en jij niet" gedoe.

[Mick]

RayNbow schreef op donderdag 22 september 2005 @ 17:53: [...] maar ik kwam laatst achter, dat ~70% van de regels van een bepaalde .c file die ik heb geschreven voor een project commentaar was. De vraag is nu, heb ik te veel commentaar getypt?

Dat hangt natuurlijk van de helderheid van je code af. Als dat een pan spaghetti is, dan zal die 70% ws. niet teveel zijn.

[RayNbow]

curry684 schreef op donderdag 22 september 2005 @ 17:54:
70% is wel weer het andere uiterste ja

Roboticles schreef op donderdag 22 september 2005 @ 17:56:
[...]
Dat hangt natuurlijk van de helderheid van je code af. Als dat een pan spaghetti is, dan zal die 70% ws. niet teveel zijn.

Tja, die 70%... dat komt omdat ik per functie een Description, Params, Returns en Pre- en Post-condities in commentaar zette en dan wil het percentage wel eens flink oplopen, vooral als de meeste functies redelijk simpel waren.

[EXX]

Commentaar is voor elke maintenance programmeur onmisbaar. Hoe meer hoe beter. Je moet nl. niet alleen de code van iemand anders (die je niet kent) onderhouden, maar ook zijn denkwijze zien te herleiden. Hoe "primitiever" de programeertaal, hoe meer commentaar erin moet. Bv. assembly code is zonder uitgebreid commentaar onmogelijk te onderhouden.

Heel belangrijk is een uitgebreide beschrijving van de functies, zoals bv. dit:

code:

; $DELIM routine: Test delimiters at parameters
; ---------------------------------------------
; This routine searches the CMD command buffer for delimiters
; HL point into the buffer. The routine returns with HL pointing at the
; first character behind the delimiter and following values:
;
: 1. End of line reached
; A=0D, Z-flag=1, C-flag=0, HL -> end of buffer
;
; 2. Comma found
; A=34, Z-flag=1, C-flag=0, HL -> character after comma
;
; 3. Other character found
; A=34, Z-flag=0, C-flag=1, HL -> location before char in command line
;
; I: HL -> buffer
; O: AF = error code

Ik voeg ook altijd een blok commentaar in aan het begin van de file met daarin informatie als:

• Modulenaam met korte beschrijving
• Hardware platform voor de software ontwikkeling
• Hardware platform waarop de software moet draaien
• Welk OS is er bij de ontwikkeling gebruikt
• Onder welk OS moet het programma draaien
• Compiler versie
• Version History

[ Voor 17% gewijzigd door EXX op 22-09-2005 18:16 ]

[Verwijderd]

zelfs ik als noob php coder gebruik altijd comment.. als ik dat niet gebruik snap ik me eigen code later namelijk niet meer (athans eerst 20 sec denken van wtf was dat ook alweer voor >_>)
oja en als ik me code op phpfreakz zet zonder comment gaan ze flippen

[mulder]

Meneer platvoet, hoe kan ik in godsnaam aan code zonder comments zien WAAROM de code iets doet? Tuurlijk kun je super duidelijke code schrijven, die precies beschrijft wat het doet, maar wat is de context? WARUM!!!

[Glabbeek]

Wat ik hier nog niet heb gelezen (of ik heb er overheen gelezen) is een andere reden om te documenteren, zeker in Java. Door concequent alle methods van JavaDoc commentaar te voorzien is het heel makkelijk achteraf een complete set documentatie te genereren, die als het goed is precies aangeeft wat de afhankelijkheden van de verschillende classes is en hoe je de code moet gebruiken. Dat is zowel handig bij het implementeren van de classes als bij het aanpassen.

Daarnaast, het is met een goede IDE bijna geen werk om JavaDoc te schijven. In Eclipse bijvoorbeeld, schijf ik eerst een method, daarna druk ik op /** en er staat een lap commentaar die ik alleen nog verder in hoef te vullen. Alle parameters worden alvast genoemd, en in het geval van de implementatie van een interface wordt alvast de @see neergezet.

[Erkens]

Glabbeek: dat is niet echt het type commentaar wat we in dit topic bedoelen. We hebben het nu meer over korte beschrijvingen wat een blok code gaat doen ipv de specificaties van je methoden etc (wat je eik _nooit_ moet vergeten)

[Glabbeek]

Erkens, dat begreep ik. Het was meer een aanvulling. In de code zelf zet ik bij de niet direct triviale code vaak commentaar in de vorm van een one-liner die in het kort aangeeft wat de code doet. Dat is zowel handig voor mezelf als ik de code later teruglees (ik heb vaak zat gehad dat ik dacht: Wat doe ik hier nu? Het werkt, maar waarom... ?) als zeker voor collega's die de code later moeten onderhouden.

Een ander punt dat ik doe is het vervangen van de zogenaamde 'magic numbers' door duidelijk genaamde constanten. Want:

Java:

String result = original.subString(5);

is toch veel minderzeggend dan

Java:

private static final int SIZE_OF_PLACEHOLDER = 5;
String result = original.subString(SIZE_OF_PLACEHOLDER);

[ Voor 8% gewijzigd door Glabbeek op 23-09-2005 10:46 ]

[EXX]

Dat laatste is gewoon goede coding practice en IMHO een basisregel voor solide code.

[Janoz]

Glabbeek schreef op vrijdag 23 september 2005 @ 00:14:

Een ander punt dat ik helaas te weinig doe is het niet vervangen van de zogenaamde 'magic numbers' door duidelijk genaamde constanten. Ik probeer het wel steeds meer te doen.

In principe doe ik dat altijd per direct en introduceer ik desnoods in dezelfde classe die constante. Later kan dit altijd nog via een refactor uit een constants class gehaald worden, of zelfs uit een configurator mbv een getter oid. Als je het een nummer laat kun je het via een normale search en een semantische search nooit weer terug vinden.

Hetzelfde doe ik trouwens in mijn views. Omdat ik bij veel applicaties van een ApplicationResources gebruik maak waaruit alle tekst gehaald moet worden schrijf ik altijd gelijk een <bean:message key="blaat"/>. Probeer later maar weer eens terug te vinden waar je nog hardgecodeerde tekst hebt staan .

[Verwijderd]

Verwijderd schreef op donderdag 22 september 2005 @ 17:56:
Mensen, een voorstel van mijn kant:
Volgens mij is mark platvoet van mening dat commentaar in code slecht is, en staat hij niet open voor een andere mening. Veel anderen zjin van mening dat code liefst zo veel mogelijk 'self explanatory' moet zijn, maar waar nodig ook gewoon in de code opgenomen moet worden, en willen mark platvoet daarvan overtuigen. Volgens mij liggen die standpunten niet eens zo ver uit elkaar, maar uit de toon van de discussie lijkt het heel anders en zwart-wit ...

Ik wel degelijk open voor een andere mening en je hebt gelijk als je zegt dat de standpunten niet eens zo ver uit elkaar liggen. Alleen zeg nou zelf, als we het niet zwart wit maken is er weinig voer voor een discussie. Doch ontbreekt van beide kanten duidelijke voorbeelden waar commentaar overbodig danwel noodzakelijk is. En ik wil best wel wat voorbeeld code neerzetten, maar dat bewijst helemaal niets. Ik ben immers vrij te kiezen wat ik wil en kan dus zo'n duidelijke code die geen commentaar behoeft neer zetten. Verre van interessant dus. Het ontbreekt ook van de voorstanders van commentaar van duidelijke voorbeelden waar commentaar noodzakelijk is. De voorbeelden die zijn neergezet bevat namelijk geen zelf documenterende code (vb: float32 f). Dus enkel code die duidelijk is opgezet en noodzakelijk commentaar bevat zal dus mijn stelling onderuit halen.

En als dat gewoon eens op een normale toon kan zou het ook wel fijn zijn. Ik hoef niet te horen dat ik volgens jullie te weinig ervaring heb. Als het echt een kwestie van ervaring is zul je met diezelfde ervaring op vrij simpele wijze kunnen aantonen dat code dergelijk commentaar behoeft.