[alg] Commentaar in code nodig of overbodig?

[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.

[NMe]

Verwijderd schreef op vrijdag 23 september 2005 @ 11:12:
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.

Hmm, dus die code van .oisyn is geen duidelijk voorbeeld? Hoe zou je het zelf dan geschreven hebben, op zo'n manier dat de naamgeving duidelijk maakt waarom je een bepaalde keuze hebt gemaakt?

Nogmaals, het is helemaal niet zo interessant om de werking van de code zelf nog eens in het commentaar weer te geven, dat kan immers ook prima bovenaan je functie/method/whatever samengevat worden. Je gedachtengang achter die werking en waarom je het nou op die manier hebt aangepakt en niet anders is echter veel interessanter voor wie het daarna nog leest.

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.

De toon van deze discussie heb je voor een groot deel aan je manier van discussiëren te danken. Misschien heb je het niet door, maar hierboven heb je heel erg selectief zitten reageren op enkel die berichten waar makkelijk commentaar op te geven was, en duidelijke argumentatie bleef uit. Dan krijg je al snel dat mensen gepiqueerd raken.

[Creepy]

Dan draaien we het om: haal de stellingen van diegene die beweren dat commentaar noodzakelijk is eens onderuit door niet triviale code te posten, opgezet op jouw manier, maar dat het toch snel duidelijk is wat de code doet op welke manier en waarom zonder commentaar.

Het enige wat je nu doet is roepen dat er een variabele naam fout is en daardoor commentaar noodzakelik is om de boel begrijpbaar te maken, dus laat nu eens zien waar je precies op doelt door een goed voorbeeld te geven.

[ Voor 3% gewijzigd door Creepy op 23-09-2005 11:26 ]

[Michali]

Ik snap zelf wel dat sommige code zo complex is dat het commentaar behoeft. Wel ben ik van mening dat je er daarnaast ook genoeg aan moet doen om de code zelf zo begrijpelijk mogelijk moet maken. In de voorbeeld van .oisyn en Zoijar zie ik bijvoorbeeld best veel decriptive variabelen staan. Dingen als a, b, y, d, ci, j en t_ bijvoorbeeld. Uitaard kun je die ondersteunen met commentaar, maar persoonlijk zou ik het zo niet doen. Ik vind het te weinig informatief en je moet dan uiteindelijk van een behoorlijk aantal variabelen in je hoofd houden wat ze nou betekenen. Met een iets meer informatieve naam is dat al een stuk gemakkelijker. Mischien dat het onderwerp zo complex is dat niet werkt, dan nog zou ik dan voor iets meer characters kiezen.

Als ik dan bijvoorbeeld naar dit statement kijk:

C++:

if (f > -y)
        return true; 

dan zet ik daar ook wel een beetje mijn vraagtekens bij. Uiteraard kun je dat dan ondersteunen met wat commentaar, maar het zou ook op een volgende manier kunnen:

C++:

bool redenVoorPositiefUitkomst = f > -y;
if ( redenVoorPositiefUitkomst )
        return true; 

Mischien krijg je dan idd wat lange variabel namen. Dat is mischien een smaak kwestie.

[Verwijderd]

@Creepy
Ik heb 1 post geleden uitgelegd waarom een dergelijk verzoek niet interessant is.

[NMe]

Verwijderd schreef op vrijdag 23 september 2005 @ 11:30:
@Creepy
Ik heb 1 post geleden uitgelegd waarom een dergelijk verzoek niet interessant is.

En wij leggen al tientallen posts uit waarom dat wel interessant is.

Jij zegt dat je op zo'n manier kan coden dat commentaar overbodig is. Niemand anders hier kan dat. Dan kun je je vast wel voorstellen dat het moeilijk te geloven is voor ons dat jij het wel kan, als je dat niet aantoont met een voorbeeld. Trouwens, jij vroeg zelf ook om voorbeelden waar commentaar noodzakelijk is, en nu je zelf eens een voorbeeld moet geven krabbel je terug?

[Verwijderd]

-NMe- schreef op vrijdag 23 september 2005 @ 11:24:
Nogmaals, het is helemaal niet zo interessant om de werking van de code zelf nog eens in het commentaar weer te geven, dat kan immers ook prima bovenaan je functie/method/whatever samengevat worden. Je gedachtengang achter die werking en waarom je het nou op die manier hebt aangepakt en niet anders is echter veel interessanter voor wie het daarna nog leest.

Dat staat in een testcase.

-NMe- schreef op vrijdag 23 september 2005 @ 11:24:
De toon van deze discussie heb je voor een groot deel aan je manier van discussiëren te danken. Misschien heb je het niet door, maar hierboven heb je heel erg selectief zitten reageren op enkel die berichten waar makkelijk commentaar op te geven was, en duidelijke argumentatie bleef uit. Dan krijg je al snel dat mensen gepiqueerd raken.

En nu stoppen met vergertje wijzen, het is zo ongelooflijk kinderachtig. Welke vraag ben ik aan voorbij gegaan?

[.oisyn]

Goed, ik ben zo welwillend geweest om mijn stukje code te voorzien van duidelijke variabelenamen (hoewel ik me afvraag hoeveel duidelijker dit nou geworden is, het leest namelijk een stuk minder prettig)

C++:

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

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

    float distToAxis = Sqrt(b.Radius()*b.Radius() + b.Height()*b.Height());
    float minDist = (distToAxis * a.Radius() + lengthOfAOrigRelativeToBProjectedOnBDir * b.Radius()) / b.Height();
    Vector3 aOrigRelativeToBF = aOrigRelativeToB - lengthOfAOrigRelativeToBProjectedOnBDir * b.Dir();
    if (aOrigRelativeToBF.LenSquared() >= minDist * minDist)
        return false;

    float positionOnAxis = a.Radius() * b.Radius() / distToAxis;
    if (lengthOfAOrigRelativeToBProjectedOnBDir > -positionOnAxis)
        return true;

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

Vertel jij mij nou eens waarom ik het op deze manier doe. Jij zegt immers dat dat af te lezen moet zijn aan de code.

[Verwijderd]

-NMe- schreef op vrijdag 23 september 2005 @ 11:35:
Jij zegt dat je op zo'n manier kan coden dat commentaar overbodig is. Niemand anders hier kan dat. Dan kun je je vast wel voorstellen dat het moeilijk te geloven is voor ons dat jij het wel kan, als je dat niet aantoont met een voorbeeld. Trouwens, jij vroeg zelf ook om voorbeelden waar commentaar noodzakelijk is, en nu je zelf eens een voorbeeld moet geven krabbel je terug?

Ik kan toch domweg een "hello world" voorbeeld neerkwakken. Dat behoeft geen commentaar, daar zal (bijna) idereen het over eens zijn. Daarom is het, nogmaals, niet interessant wat ik voor code post. Het heeft dus helemaal niks met terug krabbelen te maken enkel met de discussie waarde. Die waarde is er namelijk niet.

[.oisyn]

Verwijderd schreef op vrijdag 23 september 2005 @ 11:37:
En nu stoppen met vergertje wijzen, het is zo ongelooflijk kinderachtig. Welke vraag ben ik aan voorbij gegaan?

Wat dacht je van 99% van de vragen hier in de draad? Moeten we ze nou echt nog aan gaan wijzen ook? Wil ik best doen hoor, vermits jij dan eindelijk eens met argumenten en/of antwoorden komt. Kunnen we dat afspreken?

[TeeDee]

Toch ook maar eens reageren. Heb het topic met veel plezier gelezen, en zelfs nog dingen "geleerd". Je hebt gelijk dat "hello world" geen commentaar behoeft.

Maar wel waarom je hello world gebruikt, waar en in welke context.
Ik kan wel in elke class lib wel een hello world bakken. Waarom weet niemand, alleen ik weet dat.

Snap je?

[NMe]

Op de reactie hierboven, boven .oisyn's post reageer ik maar niet. Je hebt duidelijk de helft van het topic niet gelezen als je niet weet welke vragen en beargumentatie je ontweken hebt.

Verwijderd schreef op vrijdag 23 september 2005 @ 11:42:
Ik kan toch domweg een "hello world" voorbeeld neerkwakken. Dat behoeft geen commentaar, daar zal (bijna) idereen het over eens zijn. Daarom is het, nogmaals, niet interessant wat ik voor code post. Het heeft dus helemaal niks met terug krabbelen te maken enkel met de discussie waarde. Die waarde is er namelijk niet.

Nee, want hello world is geen complex stukje code. Het gaat hier om complexe code, en niet om een triviaal stukje code dat iedereen wel kan verzinnen. De code die .oisyn hierboven post is aardig duidelijk (zij het praktisch onleesbaar door de veel te uitgebreide variabelenamen), en toch kun je zoals hij zelf al zegt er niet de gedachtengang erachter uit halen.

[Verwijderd]

.oisyn schreef op vrijdag 23 september 2005 @ 11:41:
Vertel jij mij nou eens waarom ik het op deze manier doe. Jij zegt immers dat dat af te lezen moet zijn aan de code.

De eerlijkheid gebied te zeggen dat ik dat niet kan. maar ik vind dan ook gelijk "a.Origin()" onduidelijk. Wat zou dat moeten doen?

[.oisyn]

Je zou een engels woordenboek erbij kunnen pakken als dat de culprit is (= "dader" of "schuldige", oftewel als dat de reden is waarom je het niet snapt) . Origin betekent oorsprong, en wordt dus gebruikt om de locatie van een object in world space aan te geven.

[ Voor 20% gewijzigd door .oisyn op 23-09-2005 11:52 ]

[Michali]

@.oisyn: Zo vind ik het idd een stuk duidelijker. Alleen aan de code te lezen is nu veel begrijpelijk wat er gebeurt. Het leest nu ook meer als een 'echte' taal. Haalt echter niet weg dat het nog zo complex is dat het geen commentaar nodig heeft.

[Creepy]

Verwijderd schreef op vrijdag 23 september 2005 @ 11:30:
@Creepy
Ik heb 1 post geleden uitgelegd waarom een dergelijk verzoek niet interessant is.

Ik probeer net uit te leggen dat het wel degelijk interesant is. Ik wil weten waarom jij denkt dat commentaar niet nodig is. Ik wil me kunnen verplaatsen in jouw gedachtenwereld. Met een goed voorbeeld is dat een stuk makkelijker.
Als je een niet triviaal stukje kan posten wat geheel duidelijk is zonder commentaar, en je dit dus ook kan toepassen om andere stukken code dan zullen de meeste personen hier die nu tegen je ingaan je gelijk geven.
Maar doordat je selectief lijkt te lezen en geen voorbeeld geeft bevestig je alleen maar het beeld wat aan aantal mensen van jou hebben.

[Verwijderd]

.oisyn schreef op vrijdag 23 september 2005 @ 11:51:
Je zou een engels woordenboek erbij kunnen pakken als dat de cullprit is . Origin betekent oorsprong, en wordt dus gebruikt om de locatie van een object in world space aan te geven.

En dat vind ik dus onduidelijk. Dit is duideijk code die zichzelf niet beschrijft. oorpsrong is te algemeen en beschrijft niet duidelijk wat er mee bedoeld wordt, slechte functie naam.
Position oid komt dan al meer in de buurt.

[Yoeri]

.oisyn schreef op vrijdag 23 september 2005 @ 11:51:
Je zou een engels woordenboek erbij kunnen pakken als dat de culprit is (= "dader" of "schuldige", oftewel als dat de reden is waarom je het niet snapt) . Origin betekent oorsprong, en wordt dus gebruikt om de locatie van een object in world space aan te geven.

En hiermee is meteen aangetoond dat commentaar nodig is, aangezien de variabelenaam wel duidelijk is, maar het Mark Platvoet nog niet duidelijk was wat de code deed... ?

Of wil je serieus namen als "objectDatGelokaliseerdMoetWorden.LocatieInWorldSpace()" en "objectDatEenLevelOmhoogMag.KarakterType.Opwaarderen()" gebruiken?

[ Voor 4% gewijzigd door Yoeri op 23-09-2005 12:00 ]

[Knutselsmurf]

Creepy schreef op vrijdag 23 september 2005 @ 11:25:
Dan draaien we het om: haal de stellingen van diegene die beweren dat commentaar noodzakelijk is eens onderuit door niet triviale code te posten, opgezet op jouw manier, maar dat het toch snel duidelijk is wat de code doet op welke manier en waarom zonder commentaar.

Het enige wat je nu doet is roepen dat er een variabele naam fout is en daardoor commentaar noodzakelik is om de boel begrijpbaar te maken, dus laat nu eens zien waar je precies op doelt door een goed voorbeeld te geven.

Verwijderd schreef op vrijdag 23 september 2005 @ 11:42:
[...]
Ik kan toch domweg een "hello world" voorbeeld neerkwakken. Dat behoeft geen commentaar, daar zal (bijna) idereen het over eens zijn. Daarom is het, nogmaals, niet interessant wat ik voor code post. Het heeft dus helemaal niks met terug krabbelen te maken enkel met de discussie waarde. Die waarde is er namelijk niet.

Welk stuk van de vraag om "niet-triviale" code snap je niet?

Nogmaals, jij bent de Enige hier die beweert dat goede code geen commentaar nodig heeft. De rest van de mensen hier geeft aan dat commentaar, mits op de juiste manier gebruikt, een nuttig hulpmiddel is in het doorgronden van de code. Of dit nu je eigen code is die je op een later moment terugleest, of code van iemand anders, dat maakt niet uit.

Verder is het vaak moeilijk om een variablenaam te vinden die eenduidig omschrijft wat er in staat, zonder dat je variablenaam een heel stuk proza wordt. Met hele lange variablenamen is het lastiger teruglezen wat er precies gebeurt.

Dan kan je beter een korte variabelnaam gebruiken en in commentaar bij de assignment zetten wat die variable inhoudt.

[The End]

.oisyn schreef op vrijdag 23 september 2005 @ 11:51:
Je zou een engels woordenboek erbij kunnen pakken als dat de culprit is (= "dader" of "schuldige", oftewel als dat de reden is waarom je het niet snapt) . Origin betekent oorsprong, en wordt dus gebruikt om de locatie van een object in world space aan te geven.

Je voorbeeld is natuurlijk ook wel een beetje flauw. Ik heb totaal geen idee wat dat doet en waarom. Als jij er een boekwerk aan commentaar bij zou schrijven, dan zou ik nog geen idee hebben. Waarom? Omdat ik niets weet van 3D engines en alles daaromheen.

Het maakt heel veel uit waarvoor je code schrijft. Bij het ene project kan je niet anders omdat je een week later niet meer weet waarom het zo werkt en bij het andere project kan je het 2 jaar later nog begrijpen zonder ook maar 1 regeltje commentaar.

[Verwijderd]

Yoeri schreef op vrijdag 23 september 2005 @ 11:59:
En hiermee is meteen aangetoond dat commentaar nodig is, aangezien de variabelenaam wel duidelijk is, maar het Mark Platvoet nog niet duidelijk was wat de code deed... ?

Dat is daar helemaal niet mee aangetoond. Wat een belabberde conclusie. Het tootn aan dat deze code in zijn huidige vorm niet makkelijk leesbaar is. De oplossing daarvoor is in meerdere richting te zoeken.

[Alarmnummer]

Ik snap niet waarom mensen er nog tijd aan verprutsen. Je hebt toch wel iets beters te doen dan je tijd de verknallen aan iemand met een plaat gewapend beton voor zijn hoofd.

[.oisyn]

Michali schreef op vrijdag 23 september 2005 @ 11:55:
@.oisyn: Zo vind ik het idd een stuk duidelijker. Alleen aan de code te lezen is nu veel begrijpelijk wat er gebeurt. Het leest nu ook meer als een 'echte' taal. Haalt echter niet weg dat het nog zo complex is dat het geen commentaar nodig heeft.

Dat heeft meer te maken met je 3d math skills. Ik neem aan dat jij daar wat minder in geoefend bent? Dan helpt het idd om deze namen te hebben. Máár, jij weet ook wel wat dit betekent:

C++:

Wiel * w = auto->GetWiel(3);

, je hoeft die variabele geen "derdeWielVanAuto" te noemen. Kijk, iemand zonder math skills heeft sowieso niets te zoeken in m'n code, die kan eventuele bugs toch niet fixen. Iemand mét math skills weet wat ik met a.Origin() - b.Origin() bedoel, en dat aOrig * b.Dir() de lengte van de vector aOrig geprojecteert op b.Dir() is. Er zijn geen duidelijke variabelenamen nodig om dat te snappen.

Ik gok dan ook dat Mark Platvoet's volgende argument gaat zijn dat hij ook niet zoveel kaas heeft gegeten van 3d wiskunde, maar dat is geen argument. Ik kan je vertellen dat mijn collega, die net zoveel of zo niet nog meer wiskunde kennis heeft als ik, ook niet snapt wáárom ik doe wat ik doe zonder comments, en een mogelijk probleem dus ook nooit zal kunnen fixen zonder een dag of twee te besteden aan debuggen en reverse engineeren van de functie. In het ergste geval zal ie gewoon een compleet eigen implementatie from scratch moeten schrijven omdat ie er gewoon niet uitkomt.

[Verwijderd]

Alarmnummer schreef op vrijdag 23 september 2005 @ 12:03:
Ik snap niet waarom mensen er nog tijd aan verprutsen. Je hebt toch wel iets beters te doen dan je tijd de verknallen aan iemand met een plaat gewapend beton voor zijn hoofd.

Dan reageer je toch niet. Zoals gezegd stel ik hem expres zwart-wit. Ik heb zelf ook gewoon commentaar tussen mijn code

[.oisyn]

Verwijderd schreef op vrijdag 23 september 2005 @ 11:58:
[...]

En dat vind ik dus onduidelijk. Dit is duideijk code die zichzelf niet beschrijft. oorpsrong is te algemeen en beschrijft niet duidelijk wat er mee bedoeld wordt, slechte functie naam.
Position oid komt dan al meer in de buurt.

Sorry, maar dat ligt meer aan jouw lack of knowledge. Origin is een veelgebruikte term in de 3d wiskunde.

[Verwijderd]

.oisyn schreef op vrijdag 23 september 2005 @ 12:06:
Sorry, maar dat ligt meer aan jouw lack of knowledge. Origin is een veelgebruikte term in de 3d wiskunde.

En daarmee geef je aan dat je dus WEL eerst verstand moet hebben van de materie alvorens er sowieso naar te kijken. Of mag ik dat argument niet gebruiken omdat het je toevalligerwijs niet uit komt.

[Alarmnummer]

Verwijderd schreef op vrijdag 23 september 2005 @ 12:06:
[...]

Dan reageer je toch niet. Zoals gezegd stel ik hem expres zwart-wit. Ik heb zelf ook gewoon commentaar tussen mijn code

Maar wat is dan het doel van de discussie als iedereen het er mee eens is dat commentaar tussen je code geen doodzonde is.

[TeeDee]

Alarmnummer schreef op vrijdag 23 september 2005 @ 12:03:
Ik snap niet waarom mensen er nog tijd aan verprutsen. Je hebt toch wel iets beters te doen dan je tijd de verknallen aan iemand met een plaat gewapend beton voor zijn hoofd.

'T is vrijdag. Moet kunnen

.oisyn schreef op vrijdag 23 september 2005 @ 12:04:
[...]
ook niet snapt wáárom ik doe wat ik doe zonder comments

Hopla. Precies hetgeen hier wordt uitgedragen etc.

[.oisyn]

The End schreef op vrijdag 23 september 2005 @ 12:01:
[...]


Je voorbeeld is natuurlijk ook wel een beetje flauw. Ik heb totaal geen idee wat dat doet en waarom. Als jij er een boekwerk aan commentaar bij zou schrijven, dan zou ik nog geen idee hebben. Waarom? Omdat ik niets weet van 3D engines en alles daaromheen.

Het maakt heel veel uit waarvoor je code schrijft. Bij het ene project kan je niet anders omdat je een week later niet meer weet waarom het zo werkt en bij het andere project kan je het 2 jaar later nog begrijpen zonder ook maar 1 regeltje commentaar.

Zie mijn voorlaatste post, je hebt helaas kennis nodig om überhaupt te snappen wát ik doe, dat is de positie waarin ik zit. Ik moest met een real-life voorbeeld komen, en ik ben nou eenmaal aangenomen voor m'n 3d wiskunde kennis . Maar het punt is niet snappen wát ik doe, maar wáárom ik het doe:

Ik gok dan ook dat Mark Platvoet's volgende argument gaat zijn dat hij ook niet zoveel kaas heeft gegeten van 3d wiskunde, maar dat is geen argument. Ik kan je vertellen dat mijn collega, die net zoveel of zo niet nog meer wiskunde kennis heeft als ik, ook niet snapt wáárom ik doe wat ik doe zonder comments, en een mogelijk probleem dus ook nooit zal kunnen fixen zonder een dag of twee te besteden aan debuggen en reverse engineeren van de functie. In het ergste geval zal ie gewoon een compleet eigen implementatie from scratch moeten schrijven omdat ie er gewoon niet uitkomt.

[ Voor 27% gewijzigd door .oisyn op 23-09-2005 12:16 ]

[Verwijderd]

Alarmnummer schreef op vrijdag 23 september 2005 @ 12:10:
Maar wat is dan het doel van de discussie als iedereen het er mee eens is dat commentaar tussen je code geen doodzonde is.

Omdat je anders nooit kunt vastellen wanneer wel en wanneer niet. Aangezien alles versimpelt kan worden naar een simpel basisschool rekensommetje zou je theoretisch(/praktisch) zulke code kunnen schrijven dat commentaar overbodig wordt.

Het is voor mij puur een tijd kwestie (geld) dat ik niet elke methode dusdanig versimpel dat het begrijpelijk leesbaar is.

[.oisyn]

Verwijderd schreef op vrijdag 23 september 2005 @ 12:10:
[...]
En daarmee geef je aan dat je dus WEL eerst verstand moet hebben van de materie alvorens er sowieso naar te kijken. Of mag ik dat argument niet gebruiken omdat het je toevalligerwijs niet uit komt.

Dat kan ik ook omdraaien: het telkens maar weer gooien op laffe argumenten om ervoor te zorgen dat je mijn code niet hoeft te interpreteren, omdat de argumenten je toevalligerwijs niet uitkomen. Of nog erger: alle reacties maar links laten liggen en alleen reageren op de stukjes die niet met de inhoud van deze discussie te maken hebben (zoals deze) omdat die argumenten je toevalligerwijs niet uitkomen.

[Verwijderd]

.oisyn schreef op vrijdag 23 september 2005 @ 12:15:
Dat kan ik ook omdraaien: het telkens maar weer gooien op laffe argumenten om ervoor te zorgen dat je mijn code niet hoeft te interpreteren, omdat de argumenten je toevalligerwijs niet uitkomen. Of nog erger: alle reacties maar links laten liggen en alleen reageren op de stukjes die niet met de inhoud van deze discussie te maken hebben (zoals deze) omdat die argumenten je toevalligerwijs niet uitkomen.

Nou dan houden we het lekker daar op. Dan ben jij tenminste ook weer heppie.

[.oisyn]

Verwijderd schreef op vrijdag 23 september 2005 @ 12:15:

Omdat je anders nooit kunt vastellen wanneer wel en wanneer niet. Aangezien alles versimpelt kan worden naar een simpel basisschool rekensommetje zou je theoretisch(/praktisch) zulke code kunnen schrijven dat commentaar overbodig wordt.

En daar ga je dus de fout in. Aan dat simpele rekensommetje is zijn oorsprong niet af te lezen, en dus ook niet waarom je in hemelsnaam die ene variabele niet meeneemt in je berekening, niet wetende dat dat is omdat je er op dat moment vanuit kunt gaan dat een andere waarde waarmee je 'm moet vermenigvuldigen 0 is, zodat het resultaat altijd 0 is en je het dus ook niet bij het eindresultaat op hoeft te tellen. Iemand die de bug opspoort gaat zich, zonder comments, afvragen waarom die ene variabele nou niet wordt meegenomen, en is weer een dag kwijt om vervolgens te realiseren dat dat is omdat je kon aannemen dat een bepaalde factor 0 was. En dáár heb je nou comments voor.

Nou, hier heb je je (theoretische) voorbeeld, geen code, geen kennis vereist (ja, basisschool wiskunde, dat snap je toch wel hoop ik? ), dus geen reden meer om met drogredenen aan te komen.

Verwijderd schreef op vrijdag 23 september 2005 @ 12:17:
[...]
Nou dan houden we het lekker daar op. Dan ben jij tenminste ook weer heppie.

Bwaaaaaaap

[ Voor 18% gewijzigd door .oisyn op 23-09-2005 12:25 ]

[The End]

.oisyn schreef op vrijdag 23 september 2005 @ 12:13:
[...]
Zie mijn voorlaatste post, je hebt helaas kennis nodig om überhaupt te snappen wát ik doe, dat is de positie waarin ik zit. Ik moest met een real-life voorbeeld komen, en ik ben nou eenmaal aangenomen voor m'n 3d wiskunde kennis . Maar het punt is niet snappen wát ik doe, maar wáárom ik het doe:
[...]

Daar gaat het dan ook om; als jij hier 300 regels commentaar bij zet, dan zal ik het nog niet snappen waarom jij dat doet, hoe jij dat doet en waarvoor jij dat doet.

Ik ben er heel erg voor om 'zelfbegrijpende' code te schrijven. Het is echter in sommige gevallen (zoals jouw voorbeeld waarschijnlijk; kan ik niet echt over oordelen, want ik houd me niet bezig met 3D engines) niet mogelijk om dat te doen en dan is commentaar toch echt nodig.

Ik heb echter ook applicaties geschreven waarvan ik na 2 jaar nog steeds weet wat, waarom en hoe functies werken, zonder enig commentaar.

[.oisyn]

The End schreef op vrijdag 23 september 2005 @ 12:21:
Ik heb echter ook applicaties geschreven waarvan ik na 2 jaar nog steeds weet wat, waarom en hoe functies werken, zonder enig commentaar.

Uiteraard, sommige dingen spreken ook voor zichzelf, en dat is waar Mark het steeds over heeft. Maar wat men hier in deze draad probeert aan te tonen is dat dat simpelweg niet altijd opgaat, en dat is blijkbaar iets wat Mark niet lijkt te willen of kunnen accepteren.

[Michali]

.oisyn schreef op vrijdag 23 september 2005 @ 12:04:
Dat heeft meer te maken met je 3d math skills. Ik neem aan dat jij daar wat minder in geoefend bent? Dan helpt het idd om deze namen te hebben. Máár, jij weet ook wel wat dit betekent:

C++:

Wiel * w = auto->GetWiel(3);

, je hoeft die variabele geen "derdeWielVanAuto" te noemen. Kijk, iemand zonder math skills heeft sowieso niets te zoeken in m'n code, die kan eventuele bugs toch niet fixen. Iemand mét math skills weet wat ik met a.Origin() - b.Origin() bedoel, en dat aOrig * b.Dir() de lengte van de vector aOrig geprojecteert op b.Dir() is. Er zijn geen duidelijke variabelenamen nodig om dat te snappen.
.

Je hebt idd gelijk dat ik (veel) minder wiskunde knowledge heb dan jij. Maar wat informatievere namen helpen wel een stuk. persoonlijk vind ik w gebruiken als variable te weinig informatief. Stel dat je verder in je code variabelen/pointers naar Weg en een WegenWacht instanties hebt, hoe noem je die dan? wg en ww? Ik zou dan nog altijd kiezen voor wiel als variabelnaam ipv. w. Verder zou ik persoonlijk derdeWielVanAuto prefereren boven w. Typt mischien minder lekker, maar leest daarna wel een stuk gemakkelijk. En lezen van code doe je veel vaker dan het schrijven. Dat heeft dus altijd de voorkeur.

[Verwijderd]

Verwijderd schreef op vrijdag 23 september 2005 @ 11:12:
[...]
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.

Ik denk dat je zal moeten accepteren dat ideale code niet bestaat. Ja, alle code zou gerefactord moeten worden en duidelijke namen bevatten etc etc, maar in de praktijk zal je pragmatischer te werk moeten gaan. Je kan zelden voordat je aan een project begint alle namen van variabelen en structuren in je code uitgedacht hebben dat er nergens meer een greintje onduidelijkheid is, en als je tijdens een project dergelijke onduidelijkheden tegen komt, zal je alleen dingen aanpassen waar je tijd voor hebt en waar een pragmatische reden voor is (dwz: tijdwinst, duidelijk betere onderhoudbaarheid, etc). Een stukje documentatie toepassen is dan vaak een betere pragmatische oplossing dan het stuk code helemaal opnieuw gaan uitdenken. Soms is de impact ook gewoon erg groot en heeft het geen pragmatisch nut.

Een tweede issie is dat er soms materiekennis is bij developers die zij toepassen in het schrijven van hun software, zonder het verder te abstraheren naar een voor iedereen begrijpbare taal / structuur. Om toch mensen die onbekend zijn met deze zaken te helpen (en zichzelf te helpen als de kennis na maanden aan een ander project gewerkt te hebben is weggezakt) zal een programmeur dan liever wat regels code hieraan besteden dan zijn code herschrijven voor de leek.

Zo zijn er nog veel meer redenen te noemen waarom het misschien theoretisch beter kan, maar waar het pragmatisch de beste oplossing is om wat commentaar te typen. Het verschil ligt dan bij wat je 'beter' noemt: de theoretisch beste of de praktisch beste manier. Een aanvullend issue daarbij is dat de theoretische benadering de praktische niet ziet: "Het probleem met het verschil tussen theorie en praktijk is dat die in theorie niet bestaat, maar in praktijk vaak wel."

Ik denk dat alle voorbeelden in de wereld daar niets aan zullen veranderen, want jij zal er anders naar kijken dan anderen.

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.

Ik denk dat jij zelf ook de toon hebt gezet door heel erg stellig te beweren dat het fout was om code te documenteren, om vervolgens jouw betoog ook in deze toon door te zetten. Daarmee schoffeer jij net zo goed al de mensen die wel commentaar in hun code zetten. Je had ook kunnen zeggen dat je dat zelf niet nodig vindt / hebt omdat jouw code zichzelf voldoende beschrijft en zou dan nog wel andere meningen gekregen, maar in een heel andere toon.

Dit bedoel ik met het zwart-witte: je mag je eigen mening heel duidelijk maken, zolang je andere mensen en hun mening daarbij in hun waarde laat. Als dat niet gebeurt, zal iedereen heel defensief worden mbt hun eigen mening en die bij anderen willen opdringen, zoals dat nu gebeurt.

Daarbij lijk jij het feit dat je minder ervaren bent wel heel erg als een aanval te zien, terwijl het een constatering is van een feit, en verder niet een oordeel over jou als persoon. Verder helpt het je als je erkent dat je een eigen idee hebt en voelt dat dat goed is, maar dat dat misschien niet de universele oplossing is voor alle situaties, want je bent nog lang niet alle situatuies tegen gekomen. Wat in jou huidige situatie goed werkt zou in een andere omgeving wellicht niet werken.

Overigens zou ik ook de meer ervaren mensen op hun hart willen drukken dat zij hun ervaring ook dor schade en schande hebben opgedaan, en daarom niet hun mening zo moeten opdringen, maar gewoon minder ervaren mensen de kans geven zo te leren.

Edit:
/me koelt zijn vingers na dit wollige verhaal ...
@oisyn:

[.oisyn]

Michali: Heb je helemaal gelijk in, maar ik bedoelde het dan ook in de context van de functie die ik gepost had. Een korte functie van pakweg 15 regels met een stuk of 4 lokale variabelen. Daarin is het gebruiken van een w als referentie naar een Wiel natuurlijk heel duidelijk voor iedere lezer .

.edit: Damn you MrX, met je lange posts ertussendoor

[ Voor 12% gewijzigd door .oisyn op 23-09-2005 13:21 ]

[Janoz]

Zolang de scope van die variabele niet meer dan een paar regels is (10 oid) vind ik het niet zo'n probleem om 1 letter te gebruiken. De declaratie staat dan immers binnen het blikveld. Waneer ik een itterator voor een grote lap code gebruik is het vaak buisnessObjectItterator, maar bij een klein lusje blijft dat gewoon i of it.

[Verwijderd]

offtopic:
.oisyn: Laten we Niels er even bijhalen? Die eet zulke discussies vast als ontbijt