[Alg] Rendement van documenteren en wanneer te doen?

[Verwijderd]

Het leek me wel interessant om een discussie op te starten over het documenteren van je code.

Sommigen beginnen direct na bestudering van de specs met programmeren en als er sprake is van een applicatie die door de klant is goedgekeurd, dan schrijven ze hooguit een handleiding m.b.t. het gebruik van de software. Anderen schrijven echter vanaf het begin een technisch document (omschrijving van de processen, aanpak, UML schema's, etc.) en completeren dit ook nadat het coderen en testen is afgerond.

Probleem is vaak dat er zoveel softwareprojecten liggen te wachten op een dedicated developer, dat het documenteren erbij inschiet. Documenteert men de essentiële onderdelen en omschrijft men bijvoorbeeld ook de problemen die men is tegengekomen en de oplossing die men ervoor heeft ontwikkeld en waar men dit heeft geïmplementeerd dan kan je zelf of andere collegae in de toekomst hier hun voordeel mee doen.

Kortom, hoe gaan jullie hiermee om?

[markvt]

Ik houd een bugtracker bij met dingen die aangepast zijn nadat het programma de final heeft berijkt.

Tevens maak ik psd's voor de complexe dingen.

Documenteren alleen van de grote functies die speciaal voor een bepaald doel gemaakt zijn en de benodigde parameters en resultaten worden vermeld in de documentatie.

Voor de overige documentatie moet de source zelf bekeken worden waar extra commentaar instaat als er iets niet duidelijk is aan de hand van de code.

Een handleiding wordt uiteraard ook gemaakt voor de eindgebruiker en deze maak ik aan de hand van de te ondernemen acties door de gebruiker.

[Verwijderd]

Misschien ook leuk om een extra element toe te voegen, namelijk het toepassen van Pair Programming en Extreme Programming. In hoeverre passen jullie dit toe?

[Verwijderd]

Ik doe eigenlijk alles in mijn hoofd. Ik werk voornamelijk alleen, en [nog] niet in professioneel verband, dus voor collega's hoef ik 't niet te doen.

Wat ik wèl doe is mijn code ruimschoots becommentariëren.

[ Voor 21% gewijzigd door Verwijderd op 25-07-2004 21:43 ]

[Alarmnummer]

Ik denk dat het ook erg belangrijk is om onderscheid te maken tussen een ideale wereld en de praktijk. Er zijn denk ik maar weinig projecten waarbij de documentatie up to date is met de software. Daarom is bv op dit moment MDA ook zo hot: de documentatie is een actief onderdeel geworden van de ontwikkeling.

Persoonlijk wil ik duidelijke code zien, omdat code gewoon het meest belangrijke onderdeel van je project is: code is het eind product en dat zal dus het meest up to date zijn. Verder is bij grotere projecten zeker handig om documenten te hebben waarin het project in grote lijnen beschreven staat, maar het is verder in veel gevallen vrij zinloos om op heel laag nivo alles van commentaar te zien (afgezien van code).

Ik denk dus dat iedereen wel weet hoe het zou moeten, maar dat in de grootste gedeelte van de gevallen in de praktijk daar geen snars van terecht komt. Het komt er dan op neer hoe duidelijk je sourcecode is (en met een goed pattern vocabulair kan je daar toch vrij ver mee komen)

[ Voor 3% gewijzigd door Alarmnummer op 25-07-2004 22:03 ]

[seweso]

De beste methode is éérst je code documenteren en pas daarna de daadwerkelijke code schrijven, maar daarvoor moet je écht alles van de desbetreffende programmeertaal én beschikbare library's weten.

Dan schrijf je dus eerst dit:

PHP:

//Ophalen data via sql
//Gegevens omvormen naar xml blaat

en pas daarna:

PHP:

//Ophalen data via sql
$result = db->query("id, name, description", "company", "id = $id");
//Gegevens omvormen naar xml blaat
$xml = convertqueryresulttoxmlblaat($result);

[markvt]

Verwijderd schreef op 25 juli 2004 @ 21:42:
Ik doe eigenlijk alles in mijn hoofd. Ik werk voornamelijk alleen, en [nog] niet in professioneel verband, dus voor collega's hoef ik 't niet te doen.

Wat ik wèl doe is mijn code ruimschoots becommentariëren.

Stel dat je overlijd degene die jouw code dan zal moeten gaan bijhouden zal het allicht wel handig vinden dat er enige informatie is hoe het allemaal in elkaar steekt.

[Alarmnummer]

seweso schreef op 25 juli 2004 @ 22:05:
De beste methode is éérst je code documenteren en pas daarna de daadwerkelijke code schrijven, maar daarvoor moet je écht alles van de desbetreffende programmeertaal én beschikbare library's weten.

Onzin. Als je precies weet wat je gaat maken, dan kan je dit gaan doen. Maar in veel gevallen is dit nog niet helemaal duidelijk en is het ook niet mogelijk om van te voren de documentatie te schrijven (ik heb exact hetzelfde probleem met test driven development waarbij je eerst de tests gaat maken en daarna de code). Het ontwikkelen van software is een organisch proces en een goed ontwerp moet groeien. Ik heb meer dan genoeg vertrouwen in mijn eigen kunnen om gewoon aan de slag te gaan als ik iets nog niet helemaal begrijp (en het nergens kan vinden). Dan ga ik gewoon aan de slag en refactor continue totdat de code precies is wat ik zoek (en dus een reflectie is van wat ik ervan begrijp). Het schrijven van software is dus een organisch proces en moet je niet in een mechanisch jasje proberen te stoppen.

[ Voor 4% gewijzigd door Alarmnummer op 25-07-2004 22:12 ]

[seweso]

Alarmnummer schreef op 25 juli 2004 @ 22:09:
[...]
Onzin. ...mechanisch jasje....

Ik zie niet waarom wat jij zegt en wat ik zeg niet samen zouden kunnen gaan...

Het enige wat ik zeg is eigenlijk dat je elke keer als je een methode/functie aanmaakt je eerst kort de stappen opschrijft welke er in de functie moeten gebeuren. Dat zorgt er alleen voor dat je de documentatie niet achteraf hoeft te schrijven en betekent niet dat je alles van te voren moet weten...

[Alarmnummer]

Verwijderd schreef op 25 juli 2004 @ 18:36:
Misschien ook leuk om een extra element toe te voegen, namelijk het toepassen van Pair Programming

Nog nooit gedaan. En ik denk dat je vaak toch een situatie krijgt waarin de een zich enorm gaat storen aan de ander. Persoonlijk vind ik een stukje privacy ook wel erg fijn.

Voor codereviews ben ik trouwens wel. Ik denk dat dit een hele goeie manier is om mensen op bepaalde fouten te wijzen. En dit hoeft absoluut niet negatief opgevat te worden, maar het is een manier om een betere programmeur te worden.

en Extreme Programming. In hoeverre passen jullie dit toe?

Extreme Programming is een beetje overhyped denk ik. Zowieso aardig voor kleine projecten (en weinig mensen), maar ongeschikt voor grotere omdat er dus zo weinig wordt geconcretiseerd. Verder lijken RUP en XP ook erg op elkaar (zoek maar eens op XP vs RUP). Persoonlijk ga ik meer voor de: gebruik wat je nodig bent aanpak. Er zijn allerlei elementen die je terug ziet bij XP die me aanstaan, maar wat me niet aanstaat gebruik ik niet.

Een erg belangrijk onderdeel aan documentatie wat je trouwens bent vergeten zijn namelijk de tests, oa de unit en integration tests. Als dit goed is opgezet dan kan je precies zien wat het gedrag is van een bepaalde functie, wanneer het werk en wat eruit komt en wanneer er fouten gaan optreden. Unittesten is dus een testend stuk documentatie en jammer dat unittestcode nog redelijk in het verdom hoekje zit (het wordt niet zo gewaardeerd als normale documentatie terwijl het imho net zo belangrijk is).

[edit]
Het meest belangrijke ben ik trouwens nog vergeten. Duidelijke en heldere code heeft veel minder commentaar nodig dan onduidelijke code. Probeer dus het meest simpele te maken dat werkt (niet simpeler uiteraard). Op die manier heb je het probleem zo duidelijk mogelijk opgelost. Zie verder mijn signature.

[ Voor 10% gewijzigd door Alarmnummer op 25-07-2004 22:49 ]

[Creepy]

Alarmnummer schreef op 25 juli 2004 @ 22:01:
Persoonlijk wil ik duidelijke code zien, omdat code gewoon het meest belangrijke onderdeel van je project is: code is het eind product en dat zal dus het meest up to date zijn.

Dus jij geeft de klant code mee?

Voor de klant is een werkend iets het eindprodukt. En wat dat iets is, is geheel afhankelijk van de klant. Voordat je iets gaat maken moet je weten wat er precies gemaakt moet worden. Daarom documenteer je al voordat je begint met programmeren.

Dat je niet alles kan documenteren, of dat er wijzigingen plaats vinden tijdens het coden sluit ik hiermee niet uit natuurlijk

Tuurlijk kan je voor jezelf iets maken, en dat zelf in gebruik nemen, Maar mocht je dat willen laten gebruiken door een ander, dan ga je zeer waarschijnlijk alsnog wat documenteren.

Verder is bij grotere projecten zeker handig om documenten te hebben waarin het project in grote lijnen beschreven staat, maar het is verder in veel gevallen vrij zinloos om op heel laag nivo alles van commentaar te zien (afgezien van code).

Eens.

[Alarmnummer]

Creepy schreef op 25 juli 2004 @ 23:35:
[...]

Dus jij geeft de klant code mee?

Ja. (Alhoewel deze code wel is getransformeerd naar een executable).

Voor de klant is een werkend iets het eindprodukt. En wat dat iets is, is geheel afhankelijk van de klant. Voordat je iets gaat maken moet je weten wat er precies gemaakt moet worden. Daarom documenteer je al voordat je begint met programmeren.

Yep.. Het is denk ik wel belangrijk om dan een onderscheid te maken tussen de verschillende vormen van documentatie. Ik tot zover nog steeds erg te denken aan de documentatie voor de development. Niet zozeer de end-user documentatie.

[alienfruit]

Zelf vind ik Aspect Programming in Java, wel handig omdat je code dan in stukken wordt gebroken wat je dan weer in hapklare blokken kan documenteren. Verder heb ik er een hand van om mijn code te veel te documenteren, en op een specifieke manier ook nog Bijv. ik heb dit stukje code, waar ik nu al van weet dat de helft denk krankzinnige veel commentaar bij

Delphi:

         //
         // Drawing of glyphs for hidden characters is enabled....
         //
         if ( UseHightlight = true ) then oFont := SelectObject( aDC, OfFont ); // Select FontObject
         //
         // Get precise layout positions of original text
         //
         FLayout.nGlyphs := _MAX_LINE_LEN; // constraint glyph count
         if not FFixedWidth then GetCharacterPlacement(aDC, @tChars[tStart*_CHARWIDTH_], LongBool(tLength), LongBool(_MAX_INTEGER), FLayout.CCResult, 0); // if Fixed-width font we should take care of some stuff
         //
         // Spaces are rendered as the full stop character, this is drawn offset upwards by 25% of the line height so the dot appears in the
         // middle of the line of text.
         //
         // To ensure we draw the colors correctly, the background mode is set to TRANSPARENT (i.e. leave background alone) and,
         //                                         the foreground is set to the inverse of current background color
         // This ensures that the space 'glyph' is always visible irrespective of the color scheme in use
         //
         OldBkMode := GetBkMode(aDC);  // KEEP old Background Mode!!!
         SetBkMode(aDc, TRANSPARENT);  // SET new Background Mode!!!
         SetTextColor(aDC, ColorToRGB(cbColor) xor $FFFFFF); // invert color setting
         i := tStart; // :-)

[ Voor 3% gewijzigd door alienfruit op 26-07-2004 00:14 ]

[Verwijderd]

alienfruit schreef op 26 juli 2004 @ 00:13:
Bijv. ik heb dit stukje code, waar ik nu al van weet dat de helft denk krankzinnige veel commentaar bij
[...]

Hehe... nee hoor, je moet helemaal zelf weten hoe je becommentariëert. De lege commentaarregels vind ik dan misschien wel weer een beetje veel van het goede (?). Maar voor de rest: top (Zo doe ik 't ook, namelijk ).

[ Voor 5% gewijzigd door Verwijderd op 26-07-2004 09:08 ]

[AtleX]

Ik programmeer alleen maar als hobbyist, en na mijn vorige stage ben ik bij dat bedrijf gebleven als webapplicatieontwikkelaar. Daar maakte documentatie niet uit, het moest werken en gisteren af zijn. Ik heb daar gedrochten geschreven .

Bij mijn huidige stage ben ik de enigste programmeur, en mijn baas vindt het heel belangrijk dat ik goed documenteer met net commentaar in de code + een document erbij met de algemene werking. Hij is zelf namelijk meer grafisch ingesteld, maar als ik weg ben moet hij wel kleine wijzigingen aan de code aan kunnen brengen.

Imho is commentaar in de code erg belangrijk, zolang het maar beknopt en duidelijk is. Hele verhalen zijn overbodig en storend als je de code snel doorkijkt. Wel moet je commentaar al tijdens het programmeren erbij zetten, als je het achteraf doet worden het halfslachtige stukjes en ben je de helft al weer vergeten. Zo'n document met een beschrijving van de algemene werking vindt ik wel ontzettend handig, je kan daar veel meer uitleg en commentaar in kwijt als in de source. Dat document schrijf ik altijd pas achteraf en werk ik bij voor elke versie.

Ik ervaar het wel als nadeel dat ik mezelf programmeren heb geleerd, ik werk dus totaal niet met ontwikkelingsmodellen, etc. Wel zoek ik nog een goed boek over "hoe programmeer je goed" met uitleg over ontwikkelingsmodellen, code-opmaak, etc.

[ Voor 11% gewijzigd door AtleX op 26-07-2004 09:20 ]

[it0]

Alarmnummer schreef op 25 juli 2004 @ 22:09:
[...]

Onzin. Als je precies weet wat je gaat maken, dan kan je dit gaan doen.

Om het in het absurde te trekken, je begint zwaar te coden, 5 dagen later zie kewl, ik heb DOOMIII gemaakt, altijd al willen doen!

De meest efficiente manier van programmeren is van tevoren alles uitdenken, uitschrijven en dan hoef je het alleen nog maar te implementeren.

Veel mensen zoals ik beginnen gewoon met een idee in een hoofd dat een paar dagen heeft zitten te broeden en dan begin je te coden en globaal zie je wat het moet doen.

Maar dat soort programmeren werkt niet bij grote programma's, want je blijft dingen veranderen en herschrijven omdat bepaalde zaken bent vergeten of anders geschreven beter werken.

Kortom ik weet dat je moet beginnen met het uitdenken en documenteren van je programma.
Als je gewoon begint te coden en 2 weken later kom je terug bij die code zonder documentatie dan weet je absoluut niet wat je hebt gedaan..

[Alarmnummer]

it0 schreef op 26 juli 2004 @ 10:04:
[...]
De meest efficiente manier van programmeren is van tevoren alles uitdenken, uitschrijven en dan hoef je het alleen nog maar te implementeren.

Onzin. Als iets erg complex is dan kan je onmogelijk alles van te voren uitbedenken. Verder zul je zien dat je in de praktijk tegen allerlei zaken aanloopt die je op papier nooit hebt voorzien. Daarom incrementele ontwikkelprocessen ook zo hot. Code en design gaan hand in hand (anders kan je net zo goed volgende de waterval methode werken).

Maar dat soort programmeren werkt niet bij grote programma's, want je blijft dingen veranderen en herschrijven omdat bepaalde zaken bent vergeten of anders geschreven beter werken.

In grote lijnen stel je een architectuur op, maar die kan je onmogelijk van te voren uitwerken (of je moet wel godsellendig veel ervarign hebben).

Als je gewoon begint te coden en 2 weken later kom je terug bij die code zonder documentatie dan weet je absoluut niet wat je hebt gedaan..

Ik zou zeggen: volg een cursus netjes programmeren. Ik kan in de code die ik de afgelopen 3 aar heb geschreven altijd mijn weg terug vinden en ik ben daar geen bakken met commentaar voor nodig.

[it0]

Alarmnummer schreef op 26 juli 2004 @ 14:40:
[...]

Onzin. Als iets erg complex is dan kan je onmogelijk alles van te voren uitbedenken.

Wat houdt dat in? Dat je het maar niet doet, ik neem aan dat je niet bedoelt. Maar bij een groot project met meerdere developers dan plan je wel alles uit tot aan de functies en soms daar de invulling van.

Volgens mij is het juist de bedoeling dat je bij een complex iets juist goed vooruit denkt zodat je later niet in de knoop komt.

Het is toch hetzelfde als je bv een auto bouwt, dan werk je toch ook alles in detail uit want alle onderdelen moet wel uiteindelijk samenwerken.

[...]

Ik zou zeggen: volg een cursus netjes programmeren. Ik kan in de code die ik de afgelopen 3 aar heb geschreven altijd mijn weg terug vinden en ik ben daar geen bakken met commentaar voor nodig.

Ik kan me niet voorstellen dat bij een programma van enig formaat zonder documentatie alles meteen helder is, zeker niet als je in een team zit.

Maar goed ik heb nog nooit een genie ontmoet, want blijkbaar is het dan standaard om elke post te beginnen met het woord onzin.

[DaCoTa]

it0 schreef op 26 juli 2004 @ 16:48:
[...]
Ik kan me niet voorstellen dat bij een programma van enig formaat zonder documentatie alles meteen helder is, zeker niet als je in een team zit.

Maar goed ik heb nog nooit een genie ontmoet, want blijkbaar is het dan standaard om elke post te beginnen met het woord onzin.

Bij grote projecten is de documentatie op code nivo vaak veel minder belangrijk vergeleken met functionele documentatie.

Zeker als alle ontwikkelaars gebruik maken van goede coding standards en geen 'kijk eens wat voor geile' constructies bouwen, dan is een enkele commentaarregel om de niet voor de hand liggende uitzonderingen of redenen duidelijk te krijgen voldoende.

De noodzaak voor documentatie zit hem dan veel meer op hogere nivo's. Wat gebeurd er met alle andere functionaliteit als ik hier functionaliteit wijzig of toevoeg? Werkt dan alles nog zoals het de bedoeling was. En dan bedoel ik niet dat het stuk is, maar of het functioneel in elkaar zit zoals bedacht. Komen er geen gaten in de logica van flow control, bestaan er mogelijkheden voor data corruptie of illegal states? Vallen bepaalde beperkingen niet opeens weg of zijn constructies te omzeilen?

Al dat soort dingen beschrijf je niet in commentaar regels tussen de code, maar veel meer in losse documenten. Nofi, maar als iedere coderegel van commentaar moet worden voorzien, moet je op zoek naar betere programmeurs.

Ter info, dit is vanuit een Java standpunt. Dat is op zichzelf een erg makkelijk leesbare en duidelijke taal. Mijn statements zijn niet of minder geldig bij minder leesbare talen. Mijn ervaring bij embedded assembler programmeren is dat er naast ieder commando een stukje commentaar stond om de flow aan te geven. Maar dat kan ook liggen aan mijn mindere ervaring in assembler (als in 1 tegen 8 jaar t.o.v Java).

Aan de andere kant krijg je in assembler natuurlijk lang niet zulke grote projecten vergeleken met Java.

[Verwijderd]

Commentaarregels vind ik persoonlijk ook heel belangrijk (mits het een toegevoegde waarde kent) en documentatie m.b.t. het gebruik ervan is vooral voor de klant van belang. Verder kan het zeker handig zijn om problemen die je hebt ondervonden kort te omschrijven in je (interne) documentatie. Een goede knowledgebase waaruit ook andere developers later kunnen putten is essentieel en kent een commercieel argument. Natuurlijk blijft documenteren vaak een pain in the ass en houd het je af van het feitelijke werk, programmeren, wat nu juist zo leuk is.

[Verwijderd]

it0 schreef op 26 juli 2004 @ 16:48:
[...]


Wat houdt dat in? Dat je het maar niet doet, ik neem aan dat je niet bedoelt. Maar bij een groot project met meerdere developers dan plan je wel alles uit tot aan de functies en soms daar de invulling van.

Volgens mij is het juist de bedoeling dat je bij een complex iets juist goed vooruit denkt zodat je later niet in de knoop komt.

Het is toch hetzelfde als je bv een auto bouwt, dan werk je toch ook alles in detail uit want alle onderdelen moet wel uiteindelijk samenwerken.


[...]


Ik kan me niet voorstellen dat bij een programma van enig formaat zonder documentatie alles meteen helder is, zeker niet als je in een team zit.

Maar goed ik heb nog nooit een genie ontmoet, want blijkbaar is het dan standaard om elke post te beginnen met het woord onzin.

Kom, voel je niet persoonlijk aangevallen.
/me vindt dat jij en Alarmnummer maar even de handjes moeten schudden. Weer vriendjes?

Kijk, je kan wel zeggen dat de meest efficiente code van te voren wordt uitgedacht, maar dat is iets té kort door de bocht. Het is simpelweg niet in alle gevallen mogelijk om dingen geheel uit te denken. Soms ben je je nog niet bewust van de mogelijkheden en ga je wat test-cases maken. Wat aanklooien en zodoende steeds verder ontwikkelen.
Soms loop je pas in de praktijk tegen problemen aan. Die moet je dan realtime oplossen.
Voorbeeld: Xopus is een tool die XML en XSL transformeert in HTML en die in een WYSIWYG vorm presenteert. De gebruiker kan dingen aanpassen en Xopus past meteen de XML aan. Zeer geniaal en ik ben ook bezig met nadenken over technieken om dat mogelijk te maken.
Ik ben dus gaan brainstormen en nadenken samen met een vriend van mij en we hadden een eerste idee. Nu gaan we wat test-cases maken om vanuit de praktijk te bekijken of iets technisch wel echt haalbaar is. Met alleen stapels papier en uren denktijd kom je er gewoonweg niet. Een programma als Xopus is dermate ingewikkeld en complex dat je onmogelijk meteen alle problemen kan voorzien.

[ Voor 3% gewijzigd door Verwijderd op 28-07-2004 20:54 ]

[GrimaceODespair]

Verwijderd schreef op 28 juli 2004 @ 20:23:
Commentaarregels vind ik persoonlijk ook heel belangrijk (mits het een toegevoegde waarde kent)

Mijn ervaring hiermee is dat commentaar altijd een toegevoegde waarde heeft, zelfs als het redundant lijkt (behalve natuurlijk als het commentaar misleidend of gewoon fout is).

Een regel als:

C++:

...
i++;
...

(1) valt niet op, en (2) zegt niets. Het zou al wat meer zeggen als i een beschrijvende naam had. Maar met commentaar erbij los je beide problemen in 1 keer op.

C++:

...
// Increase body count
bodyCount++;
...

Ik heb dan ook liever code met meer wit- en groenregels (of whatever je syntax coloring is) dan zwart. Zeker bij het debuggen kan 1 beschrijvende regel het verschil betekenen tussen een typo ontdekken en een dag kwijt zijn.

En wat betreft documentatie. Die schiet er in de praktijk in eerste instantie meestal bij in, maar er zijn van die momenten wanneer er toch op ingezet wordt. Want als je het puur bedrijfseconomisch bekijkt, kunnen die paar uurtjes documenteren een dubbele winst betekenen als een ander de problemen moet gaan oplossen. En al helemaal als de schrijver van de code niet meer bereikbaar is.

Ik heb ook de indruk dat in grote bedrijven eerder structureel met documentatie wordt omgegaan dan in kleinere. Ik heb in ieder geval op 'school' altijd geleerd dat je geen regel moet coden voordat je functionele beschrijving op papier staat. Dat hoeft geen incrementeel proces in de weg te staan, je moet er enkel rekening mee houden. Maar goed, vooraf documenteren blijft voor mij nog vaak theorie, soms misschien tegen beter weten in.

[Creepy]

GrimaceODespair schreef op 28 juli 2004 @ 23:25:
[...]

Een regel als:

C++:

...
i++;
...

(1) valt niet op, en (2) zegt niets. Het zou al wat meer zeggen als i een beschrijvende naam had. Maar met commentaar erbij los je beide problemen in 1 keer op.

C++:

...
// Increase body count
bodyCount++;
...

Sorry, maar dit vindt ik echt teveel commentaar.
Want met een goede naamgeving los je allebij je punten op. Als bodyCount++ je niks zegt, dan zegt "increase body count" je ook helemaal niks. Leg dan uit WAAROM je bodyCount ophoogt, en leg niet uit dat je dat doet, aangezien dat echt wel uit de code te lezen is.

[Alarmnummer]

GrimaceODespair schreef op 28 juli 2004 @ 23:25:
Mijn ervaring hiermee is dat commentaar altijd een toegevoegde waarde heeft, zelfs als het redundant lijkt (behalve natuurlijk als het commentaar misleidend of gewoon fout is).

Ik wil dat code op zich goed te lezen is. Veel complexe zaken wegrefactoren. Maar ik wil dus zeker niet al het voor de hand liggende van commentaar voorzien.

Een regel als:

C++:

...
i++;
...

(1) valt niet op, en (2) zegt niets. Het zou al wat meer zeggen als i een beschrijvende naam had. Maar met commentaar erbij los je beide problemen in 1 keer op.

C++:

...
// Increase body count
bodyCount++;
...

Tja.. het heeft dus totaal geen toegevoegde waarde. Als ik een regel commentaar ergens neer zet, dan is er dus iets 'lastigs' aan de gang. En dat wil ik graag toelichten. Maar voor de hand liggende zaken is imho zelfs slecht om te documenteren omdat je meer tekst hebt om door heen te worstelen + onderhouden!


Verder stel ik wel erug veel prijs op goeie naamgeving. Niet alleen van variablen, maar ook packages, classes, interfaces en methodes (en zelden meer dan 3 argumenten). Goeie code moet te lezen zijn als een boek.. en je moet niet de hele tijd van hot naar her springen om te begrijpen wat er gaande is. (Meestal is dat een kenmerk van een slecht ontwerp en dus gebrek aan goeie oo technieken/patterns).

Voorbeeld van commentaar binnen een methode. Hier heb ik dus iets aan omdat er dus complexe zaken gaande zijn. Ik wil dan uitleg waarom ik iets doe.

Java:

public void setUpQuery(Query query) {
        if (query == null)
            throw new NullPointerException("query can`t be null");
        if (_currentQuery != null) {
            //Als er op dit moment al een query onder evaluatie is, wordt de toestand
            //van de abstractmachine tijdelijk opgeslagen in een queryframe en deze
            //wordt op de framestack geplaatst. Op het moment dat de query klaar is
            //met evaluatie, kan deze queryframe weer opgehaald worden (bovenste element)
            //van de framestack en kan de omgeving weer hersteld worden.
            QueryFrame frame = new QueryFrame(this);
            _frameStack.push(frame);
        }

        _currentQuery = query;
        _ip = 0;
        _code = _compiler.compile(query).getCode();
    }

En niet bij zulke triviale zaken als een i++

[ Voor 47% gewijzigd door Alarmnummer op 28-07-2004 23:58 ]

[GrimaceODespair]

Alarmnummer schreef op 28 juli 2004 @ 23:31:
Maar voor de hand liggende zaken is imho zelfs slecht om te documenteren omdat je meer tekst hebt om door heen te worstelen + onderhouden!
[...]
Goeie code moet te lezen zijn als een boek

Misschien heb ik wel gewoon een andere insteek. Als ik een lap code voor me krijg waaraan ik iets moet fixen, wil ik de flow kennen zonder de precieze werking van de code te moeten uitzoeken. Dat kan inderdaad via heldere code met betekenisvolle naamgeving. Maar dat kan dus ook via commentaar.

Als ik dus boven elke regel commentaar heb, kan ik de code 'als een boek' lezen. Uiteraard ga ik er dan ook van uit dat de functies een beetje normale lengte hebben (vuistregel is zeker: "niet langer dan 60 regels"?), anders wordt het inderdaad onoverzichtelijk.

Nu ben ik iemand met vrij weinig discipline, maar vreemd genoeg ben ik nogal consequent met het plaatsen van commentaar. Dus wat betreft onderhoud, is het voor mijzelf geen groot probleem.

Overigens helpt het plaatsen van commentaar bij elke regel ook bij het structureren en helder krijgen van je code.

[alienfruit]

Ik ben van mening dat je de werking van bepaalde functies en/of classes ook moet uitleggen in de code zelf dan alleen in de documentatie erbij. Dus als jij een classe gemaakt hebt voor het tekenen van de gutteer of de TextPaintEngine (voor een editor) dan lijkt me het fijn als je uitlegt hoe wat van bijv. Text Highlight Flow (welke checks, wat wanneer etc.) en overigens overvloedig gebruik van commentaar maakt eigenlijk niet uit Programma wordt er niet groter door

[GrimaceODespair]

alienfruit schreef op 29 juli 2004 @ 00:34:
overigens overvloedig gebruik van commentaar maakt eigenlijk niet uit Programma wordt er niet groter door

Nee, maar volgens de collegae wel onleesbaarder/ononderhoudbaarder (is dat een woord?), wat ik op mijn beurt dus betwist.

[ Voor 7% gewijzigd door GrimaceODespair op 29-07-2004 00:35 ]

[DaCoTa]

alienfruit schreef op 29 juli 2004 @ 00:34:
[...]
en overigens overvloedig gebruik van commentaar maakt eigenlijk niet uit Programma wordt er niet groter door

[rml][ Java] Compiler maakt van kleinere java kleinere class file?[/rml]

[Creepy]

GrimaceODespair schreef op 29 juli 2004 @ 00:35:
[...]
Nee, maar volgens de collegae wel onleesbaarder/ononderhoudbaarder (is dat een woord?), wat ik op mijn beurt dus betwist.

Onderhoudbaarder wil ik niet zetten. Minder makkelijk leesbaar wel. Je mag van een ontwikkelaar wel een beetje niveau verwachten zodat je niet elke regel van commentaar hoeft te verzien. De code moet lezen zoals een "boek", niet het commentaar Het commentaar is er alleen maar ter ondersteuning van.

Maar jij geeft dus bij elke regel code ook echt minimaal 1 regel commentaar? Ik zou gek worden als ik dat zou lezen. Alsof jij iedereen die je code leest stukken dommer verwacht dan jij bent. Daarnaast zou ik ook gek worden als ik dat ook zou moeten doen.
Als een "bodyCount++" niet helder genoeg is voor een ontwikkelaar, dan wordt het voor die ontwikkelaar tijd om een andere hobby te zoeken

[whoami]

seweso schreef op 25 juli 2004 @ 22:05:
De beste methode is éérst je code documenteren en pas daarna de daadwerkelijke code schrijven, maar daarvoor moet je écht alles van de desbetreffende programmeertaal én beschikbare library's weten.

Dan schrijf je dus eerst dit:

PHP:

//Ophalen data via sql
//Gegevens omvormen naar xml blaat

en pas daarna:

PHP:

//Ophalen data via sql
$result = db->query("id, name, description", "company", "id = $id");
//Gegevens omvormen naar xml blaat
$xml = convertqueryresulttoxmlblaat($result);

Dat vind ik nu een voorbeeld van zinloos commentaar.
Je kan uit die 2 regels code ook wel afleiden wat die code doet; zodat dit commentaar onnodig is.

[Alarmnummer]

GrimaceODespair schreef op 29 juli 2004 @ 00:35:
[...]
Nee, maar volgens de collegae wel onleesbaarder/ononderhoudbaarder (is dat een woord?), wat ik op mijn beurt dus betwist.

Als je veel commentaar hebt wat geen toegevoegde waarde heeft dan:
-onderhoud code is lastiger, doordat je ook het vele commentaar up to date moet houden. Zeker in moderne omgevingen met allerlei refactor functionaliteit kan dat nog wel eens problemen opleveren.
-moet je meer doorlezen.

Ik ben dus absoluut niet tegen commentaar. Maar je moet het wel gebruiken op plekken dat het nodig is, zodat het ook tot zijn recht komt.

[cavey]

Goed documenteren, als ik ergens vaak tegen aan ben gelopen in m'n nog prille bestaan als software engineer, is het wel het ontbreken van documentatie.

Al is het maar een klein beetje, dat je iets zwart op wit hebt staan van hoe een bepaald rapport er bijv. uit heeft moeten zien. Scheelt je enorme kopzorgen als je de boel opeens om moet gooien omdat management beslist "ownee, toch liever zo en zo" ...

Of als je een stuk software ontwikkeld, is het echt wel handig als je een globaal idee hebt van hoe alles in elkaar zit (business software is toch meestal 3 lagen model -> GUI / Business layer / Data layer), interfaces definieren, in geval van OO ontwikkeling nette UML classes erbij, use cases etc.

Gewoon, duidelijk gestructureerde documentatie.... hoe miniem ook, helpt ENORM bij het ontwikkelen. Goed, tijdens het ontwikkelen veranderd er wellicht nog wat aan de specs, maar je moet je poot redelijk stijf houden en durven/kunnen zeggen: sorry, we maken eerst dit, al het overige komt op de wish list terecht en wordt later ge-evalueerd en eventueel geimplementeerd (maar je houdt er ondertussen wel rekening mee in je ontwerp!!).

Commentaar in je code zetten is ook reuze handig, wees redelijk spaarzaam, countertjes enzo documenteren (zoals de notoire i++, j++ etc counters ) zijn meestal niet nuttig om te documenteren..... aangezien ze toch in for loopjes gebruikt worden.

Andere counters, die op meerdere plekken voor komen of wel een duidelijke betekenis hebben uiteraard wel netjes beschrijven, hetzij kort in je code, hetzij in je dead-tree documentatie (in electronische vorm )

Verder, ingewikkelde procedures/algoritmes/whatever, altijd documenteren! Hoe spaarzaam ook. Nu weet je nog hoe het werkt, over een half jaar weet je dat echt niet meer (tenzij je er nog steeds aan zit te coden over een half jaar, maar als je het een half jaar laat liggen .... en je hebt andere dingen tussen door zitten coden ...)

Tja, ik merk hier al wel dat er toch beetje gemakkelijk wordt gedaan over documentatie.. maar je kan beter 2 weken vet ontwerpen, documenteren etc..... en testen verzinnen, en dan 1 week hard bikkelen aan je code..... dan dat je 1 dag aan je code spendeert... er mara van uit gaat dat het idee in je hoofd goed is... en lukraak gaat coden.

"oh, dit nog nodig, dat nog nodig, dit is ook wel handig. shit daar niet eerder aangedacht, hmm.. ff erin kludgen.. tralala, ranzige code, naja, ruim ik later wel op als ik wat meer tijd heb... ow dat moet er ook nog in. Tuurlijk kan dit erbij, geen probleem joh" en 5 weken later zit je met een half product dat netjes aan elkaar is gelijmd met brakke lijm ... er hoeft maar een verkeerde parameter aanroep gedaan te worden, of een input error en je hele app crasht..." ...

bekend fenomeen? ja? ...

[Verwijderd]

Meestal is er toch weinig documentatie merk ik in de praktijk. Documentatie wordt alleen echt toegepast bij grote projecten met een langere looptijd en een groter budget. Meestal wordt het gehouden bij FO, TO (waaronder object model), en Use Cases.

Het enige wat ik persoonlijk uit documentatie wil afleiden is, als ik hier wat aanpas welke andere stukken code zijn er van afhankelijk zodat ik iets niet breek.

[PrisonerOfPain]

komakeef schreef op 29 juli 2004 @ 22:52:
"oh, dit nog nodig, dat nog nodig, dit is ook wel handig. shit daar niet eerder aangedacht, hmm.. ff erin kludgen.. tralala, ranzige code, naja, ruim ik later wel op als ik wat meer tijd heb... ow dat moet er ook nog in. Tuurlijk kan dit erbij, geen probleem joh" en 5 weken later zit je met een half product dat netjes aan elkaar is gelijmd met brakke lijm ... er hoeft maar een verkeerde parameter aanroep gedaan te worden, of een input error en je hele app crasht..." ...

bekend fenomeen? ja? ...

VS.net heeft daar een leuke feature voor, ///TODO: schrijf gewoon op wat je nog moet doen en het komt in je todo lijstje te staan. Kun je het implementeren als je er wel tijd voor hebt . Mocht je het er al hebben staan heb je ook nog ///HACK:, ///UNDONE en de mogenlijkheid zelf van die tags te genereren. Werkt erg prettig (sowieso werkt het /// commentaar erg fijn)

[JaQ]

[...]
Onzin. Als je precies weet wat je gaat maken, dan kan je dit gaan doen. <<snip>>
[...]

En dat is dus percies waarom je waarschijnlijk je code minimaal 1 keer herschrijft voordat je het in productie durft te brengen. Als je op voorhand de flow van je programma hebt gedocumenteerd, schrijf je in 1 keer een goed programma. Ik denk dat je zelf ook veel uit de hand gelopen "proefbalonnetjes" (om maar eens een mode woord te gebruiken) tegen komt die tot in productie doorwerken. Als je tot de conclusie komt dat je daar regelmatig op loopt te schelden, moet je hier eens nadenken over de oorzaak van dit alles.

Als je eerst bedenkt hoe je je programma wilt laten werken en dan gaat schrijven, heb je in 1 keer mode schone code met een duidelijk flow. Uiteraard weet ik ook dat dit in de praktijk niet altijd mogelijk is, omdat de functionele eissen niet altijd duidelijk zijn. Schrijf dan echter ook geen code, maar zoek eerst uit wat iemand nou echt wel, zonder maar wat te produceren (want dat soort ongestrureerd uren-schrijf gedrag is de reden dat er zoveel konijn-uit-toverhoed software in omloop is). Ook is de mate waarin je iets opschrijft iets anders dan de complete flow bedenken. Ja, documentatie die tot op detail gaat is vaak stom vervelend om te lezen/bekijken, maar als jij voor mij een stuk software zou schrijven zou ik toch echt, voordat je ook maar 1 letter programmeerd hebt, eerst jouw gedachtengang voor je programma willen zien. Juist als de zaken complex zijn wil ik dat, gewoon omdat ik er vanuit ga dat je mens bent en dus (net zoals ik) soms ook blinde vlekken in je blikveld hebt.

Het niet documenteren van code / programmaflow is een mate van amateurisme die ik helaas te vaak tegen kom binnen organisaties die zichzelf professioneel noemen. Hoezo versiebeheer, hoezo bugtrackers en hoezo gestructureerd programmeren. Je kan nog zoveel buzzwoorden over de muur gooien, als je niet duidelijk maakt hoe jouw gedachtenkrokels meanderen (want dat doe je met goede documentatie) mis je de kern van het verhaal. Dat je dit vervolgens met UML, PSD's, ERD's doet, of wat je op dat moment voor dat ontwerp ook van toepassing vind, is voor mij persoonlijk minder van belang, zolang ik maar begrijp wat je doet.

Ik durf zelfs zo ver te gaan dat iemand een programma voor je kan ontwerpen, zonder zelf ook maar 1 letter code te kunnen schrijven. Programmeren is een technisch trucje dat je helpt om een (abstract) model / idee te beschrijven in machinetaal, niets meer en niets minder.

[disclaimer]
De hierboven gestelde mening is de mijne. Je hoeft het hier natuurlijk niet mee eens te zijn en indien je dat niet bent zal ik je echt niet minder respecteren of behandelen dan iemand die het wel met me eens is. Dit is dus niet persoonlijk bedoeld richting wie dit dan ook niet op deze wijze oppakt.
[/disclaimer]

[Alarmnummer]

DrFrankenstoner schreef op 30 juli 2004 @ 00:10:
[...]
En dat is dus percies waarom je waarschijnlijk je code minimaal 1 keer herschrijft voordat je het in productie durft te brengen.

Ik denk dat ik wel kan zeggen dat ik een van de zwaarste unit tester bent die op dit forum rondloop. En verder ben ik een ongelovelijke zeiker op het gebied van ontwerp, check mijn topics maar. Ik ben dus helemaal voor een superstrak gaaf, geil en opwindend ontwerp. Maar ik weet uit ervaring dat normale code niet komt vanaf papier, maar zich het beste vormt vanuit de loopgraven. Ik ben in dat opzicht meer een xp aanhanger dan de traditionele waterval methode die jij aangeeft.

Als je op voorhand de flow van je programma hebt gedocumenteerd, schrijf je in 1 keer een goed programma.

Het ligt er erg aan wat voor applicatie je ontwikkeld en hoeveel ervaring je ermee hebt. Als het een routine klus is, tja.. dan kan je van te voren alles uit ontwikkelen. Helaas zijn de meeste klussen uniek met hun eigen eigenaardigheden en daarbij kan je gezien de huidige complexe stand van zaken nu niet eenmaal iets ontwerpen en daarna schrijven. Je komt altijd achter nieuwe zaken (bv performance, security). Of een ontwerp dat nu eenmaal te complex is. Oja.. en op eht moment dat je UML tot op het code nivo gaat doorvoeren, check dan een goed UML boek: je bent dan veel en veel te ver gegaan.

Als je eerst bedenkt hoe je je programma wilt laten werken en dan gaat schrijven, heb je in 1 keer mode schone code met een duidelijk flow. Uiteraard weet ik ook dat dit in de praktijk niet altijd mogelijk is, omdat de functionele eissen niet altijd duidelijk zijn. Schrijf dan echter ook geen code, maar zoek eerst uit wat iemand nou echt wel, zonder maar wat te produceren (want dat soort ongestrureerd uren-schrijf gedrag is de reden dat er zoveel konijn-uit-toverhoed software in omloop is).

Het ligt weer aan het soort applicatie dat je ontwikkeld. Als je nummer 10.001 van een of andere data entry applicatie maakt waaraan weinig technologische risico`s zijn verbonden.. ach tja.. dan kan je van te voren alles tot in de puntjes uitdokteren. Helaas zijn applicaties tegenwoordig te complex om alles te ontwerpen. Dat wil niet zeggen dat je maar een eind in het wild moet kloppen.. zeker niet. Maar dat ontwerp en code kloppen hand in hand gaan. Ondekkingen die ik doe tijdens het testen kan ik direct terug koppelen aan het ontwerp (dus eventueel wijzigingen doorvoeren als dat moet). Dit krijg je dus niet voor elkaar als je zo statisch gaat werken. Een goed ontwerp groeit organisch en het is geen mechanisch proces.

Ik durf zelfs zo ver te gaan dat iemand een programma voor je kan ontwerpen, zonder zelf ook maar 1 letter code te kunnen schrijven. Programmeren is een technisch trucje dat je helpt om een (abstract) model / idee te beschrijven in machinetaal, niets meer en niets minder.

Het ligt eraan. Als ik een groot systeem ga ontwerpen ga ik ook eerst kijken wat voor architectuur ik wil gaan gebruiken. Maar dit zijn grote guidelines om binnen te ontwerpen en ik ga niet tot in de kleinste details ontwerpen. Kleinere details zie ik wel weer als ik met het testen/coden bezig ben. Dan blijkt wel wat de beste oplossing voor een bepaald probleem gaat worden (en dat zijn dus dingen die je alleen met erugh veel ervaring van te voren kan bepalen. Voor de leken onder ons is het dus een kwestie van observeren en dan eventueel aanpassen -> incrementeel ontwikkel proces).

Dit is dus niet persoonlijk bedoeld richting wie dit dan ook niet op deze wijze oppakt.

Pfff. jammer hoor

[ Voor 5% gewijzigd door Alarmnummer op 30-07-2004 01:14 ]