[alg] Commentaar in code nodig of overbodig?

[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