[DISCUSSIE] Code becommentariseren is onnodig.

[TrueChaoZ]

Stelling: Code becommentariseren is onnodig. Het kost alleen maar tijd, dus geld, en maakt je code-bestanden groot en onleesbaar.

Terwijl jij je misschien al een mening aan het vormen geweest ben bij het lezen van "[ STELLING ] This or not to this (relatieve paden/scopes) (http://www.flashfocus.nl/forum/showthread.php?p=32299#post32299)" gaan we hier nog een stukje verder in op het maken van goede en heldere code-bestanden. Wees vooral niet bang om je mening 'ongezout' te geven, maar houd het wel respectvol naar elkaar toe. Vergeet ook niet om je mening te onderbouwen, eventueel met externe links, interne links en/of voorbeelden, zodat iedereen begrijpt wat je bedoelt en daar weer zinnig op kan reageren.

Heb je de smaak te pakken? Kijk dan ook even naar de "[ STELLING ] Hoofd-movie preloader vs. oEF bytes check (preloaders) (http://www.flashfocus.nl/forum/showthread.php?t=3848)".

[Robin]

ONEENS :)

Ik ben nu al 4 dagen aan het prutsen in een bestand die een 'andere' stagair een keer gemaakt heeft. Overdoen schiet niet op en het is erg veel. Als er commentaar bij had gestaan had ik het veel sneller kunnen doen. Vooral programmeurs die $a t/m $z gebruiken als vars.

[Roenes]

Zozo, lekker bezig TrueChaoZ. :D

Maar het commenten van je AS. Allereerst vind ik dat je stukken AS die voor zich spreken niet moet commenten. Dat is overbodig. Delen van code die ingewikkeld in elkaar zitten of waarvan je denkt dat je over een tijd niet meer precies weet wat er gebeurt, is altijd slim om te commenten. Ook code die naar andere personen gaat moet je op de juiste stukken commenten en dus niet alles.

Maar doe ik dit ook? Neej, vaak niet. Dat komt door het volgende: bijna alle code die ik maak, blijft bij mij. Ik werk meestal alleen waardoor alleen ik de code moet kunnen begrijpen. Doordat ik er dan zelf mee bezig ben, neem ik de moeite niet om het te commenten. Als ik een tijd later terug kijk naar een AS file, heb ik daar soms wel spijt van.

Ik vind wel dat als je met andere samenwerkt, dat je dan wel je code moet commenten en dan het liefst volgens een vaste afspraak. Dus dat iedere comment van welke persoon dan ook op dezelfde manier is opgebouwd. Hierdoor blijft het geheel dus consistent.

Anyway, commenten vind ik iets goeds, maar ik doe het zelf amper tot niet :)

[Tha Narie]

- Als je goede code schrijft, zou commenten niet nodig moeten zijn ;)
- Commenten tijdens het bouwen van je code werkt niet lekker, omdat je vaak dingen verandert, en het commenten op die manier veel tijd in beslag neemt. (comments schrijven die je later weer weg haalt)
- Als je project/file klaar is zou je alles moeten commenten, maar dan heb je het vaak te druk, en moet je aan nieuwe dingen werken ;)
- Als je later terug duikt oude code, kost het minstens zoveel tijd om het te snappen, dan als je het voorheen had commented ;)

[Dauntless]

Weer een leuke discussie, TC :)

1ste punt van Narie is wel echt niet waar... Het is niet omdat je de code begrijpt dat je snapt waarom het zo is... Simpel voorbeeld: afstand tussen twee punten. Da's de stelling van pythagoras, maar als je dat niet zegt (of bv //A² = B² + C²) dan kan de lezer misschien totaal niet doorhebben waaróm je dat juist doet...

Daarnaast becommentarieer ik zelf ook ZELDEN. Ik volg Roenes eigenlijk! (Da's namelijk de nieuwste trend ;)). Ik code ook bijna altijd voor mezelf en dan schrijf ik er weinig documentatie bij. Maar neem nu die A* die ik hier had gepost, die stond VOL documentatie!

[mech7]

Heeft AS geen tool dan die autmatisch een API genereert ?

[Roenes]

Ik volg Roenes eigenlijk! (Da's namelijk de nieuwste trend ;)).Op deze manier krijg ik het halve FF team achter me ;)

[TrueChaoZ]

Heeft AS geen tool dan die autmatisch een API genereert ?
Er is geen officiële ASDoc oid, je zou wel gebruik kunnen maken van een soort JavaDoc of PHPDoc achtig iets. Ik kwam dit tegen op www.senocular.com, ASDocular (http://www.senocular.com/projects/AS2Docular/actionscript.php). Als je goed zoekt op het internet zijn er nog wel meer van dit soort projects, maar ja zolang er niet echt een standaard is, is dit dus niet echt handig om te gebruiken. Daarnaast lijken JavaDoc/PHPDoc en soortgelijke wel erg op mekaar en als je dus jezelf al aanleerd om dit te gebruiken zal je later (als er ooit nog een officiële ASDoc komt) maar weinig hoeven aan te passen aan je style en documenten. Maar hier mogen ze van mij bij Macromedia ook wel eens flink aandacht aan gaan geven, net zoals bijvoorbeeld de optie om tijdens het developen je comments onzichtbaar te kunnen maken.

[Roenes]

Dat hele AS schermpje mag macromedia wel eens uitbreiden. Ik bedoel: standaard opties van externe editors heeft flash niet eens. Ik denk dan aan code folding en dergelijke. :)

Maar das weer een andere discussie ;)

[Dauntless]

Ik heb voor die A* Natural Docs voor SE|PY gebruikt... (I LOVE SE|PY) :D

[kH_]

Het becommentariseren van code is extreem belangrijk, wanneer je gezamenlijk aan projecten werkt en er enorm veel sharing van code plaatsvindt. Op zich is het belangrijk om met je ontwikkelteam een commentaar standaard te verzinnen, zodat iedereen binnen een project exact dezelfde ideeen heeft bij becommentariseerde interfaces. Het becommentariseren van algoritmen e.d., of simpel gezegd....de implementatie van een interface an sich is eigenlijk alleen nuttig voor de programmeur zelf. Vraag jezelf gewoon bij stukken code telkens af hoe groot de kans is, dat een geprogrammeerd stuk functionaliteit in de toekomst aangepast gaat worden (en die kans is bij grote projecten toch in 99% van de gevallen aanwezig). Indien deze kans er is, zet er dan commentaar bij en vraag mede-programmeurs of ze snappen wat jij ermee bedoelt (TIP: vraag of ze in hun eigen bewoording kunnen uitleggen hoe jouw code werkt, wat het precies doet en luister daar naar. Op die manier weet je direct of jouw commentaar op de goede manier geinterpreteerd wordt). In een later stadium voelen ontwikkelaars binnen een team elkaar feilloos aan en zijn elkaars eigenaardigheden voor wat betreft programmeerstijlen e.d. wel gewend. Op zich is het dan niet meer nodig om fysieke implementaties van interfaces te becommentariseren, maar ja...dat is persoonlijk.
Je kunt ook extreem ver gaan en gewoon uitgaan van de stelling 'if it was hard to write, it should be hard to understand', maar die stelling is volgens mij bedacht door een nerd die alleen achter de geraniums op een stoffige Toshiba code loopt te kloppen, dus volgens mij:

-Becommentariseren van interfaces -> ALTIJD, aangezien je NOOIT weet welke klanten gebruik gaan maken van jouw interface
- Becommentariseren van de implementatie van een interface -> als je het zelf zinvol vindt, doen....zo niet....waarom vraag je het jezelf dan nog af?

[Pimm]

Ik doe het eigenlijk nooit, alleen om grote lappen code uit elkaar te houden (dan zet ik er een paar lege comment regeltjes tussen, een normale regel werkt niet omdat ik dat "zet de code automatisch goed"-knopje constant gebruik). Vooral in games met één frame met daarin alle codes kan het onoverzichtelijk worden als je dat niet doet.

Voor andere mensen (die mijn open source projecten willen hebben), die denken maar even mee en als ze het niet begrijpen zijn ze welkom met hun vragen.

Conclusie: Als ik het niet voor mezelf doe doe ik het helemaal niet.

Oh, en kH's eerste argument is goed, ik gebruik dus wel af en toe comment regeltjes als ik bang ben dat de mensen waarmee ik iets maak de code niet zullen begrijpen maar meestal ben ik toch de enige die aan de codes sleutelt.

[Laiverd]

Ik zou een andere stelling neer willen zetten: mensen die hun code niet van commentaar voorzien dragen hun steentje bij een een inefficient en tijdrovend werkproces, zijn waarschijnlijk weinig communicatief en vergroten bovendien de kans op fouten door een verkeerde interpretatie van hun code. ;) Het mag duidelijk zijn dat ik me geheel bij KaleHufter aansluit.

John

[Folkert]

Sja, geen handleiding doen bij een gecompliceerd moederbord met allemaal knopjes ;) dan gaat het lekker.
Oftewel, wil je herbruikbare code schrijven of uberhaupt later nog weten wat welke var nu ook alweer betekende dan is commenten een must.
Als je een beetje thuis bent in OSFlash zul je ook redelijk bekent zijn met het commenten, neem bijvoorbeeld een ARP.
Een prachtig framework met even zo duidelijke helder en logische code. Om thanaries 'als je goed code hoef je niet te commenten' even onderuit te halen. Zonder comments ARP in gebruik nemen (dwz zonder comments in de ARP scripts) word het denk ik lastig de heldere werking te doorgronden.
Het commentaar schrijven kost weinig moeite, je weet immers wat je gaat doen of aan het doen bent, dus echt veel meer tijd ben je niet kwijt, wel win je heel veel tijd (of anders je collegas wel).

conclusie: de stelling zuigt big time ;)

[mknol]

comment is alleen voor je copyright tekst toch? :P

[Roenes]

comment is alleen voor je copyright tekst toch? :PZo wordt het vooral door designers gebruikt jah ;):P

[mknol]

Zo wordt het vooral door designers gebruikt jah ;):P
Laatst een flaatje gedownload en dat zag er ongeveer zo uit:


// ============================================
// ============================================
// ============================================
//
// NIETS VAN DEZE CODE MAG GEBRUIKT WORDEN
// ZONDER TOESTEMMING. © NAAM PERSOON
//
// ============================================
// ============================================
// Aan deze tutorial is veel aandacht besteed
// en het is niet de bedoeling om deze code
// klakkeloos te copieeren
// ============================================
// ============================================
// ============================================
gotoAndPlay(20);
// deze code zorgt ervoor dat u naar frame 20 gaat.

Commentaar is dus onnodig

[Roenes]

Dat is idd wel een beetje overkill :D

[SaphuA]

Hahahahahah :D Dat ie die source vrijgeeft zeg...

Ik commenteer alleen code om het er wat netter uit te laten zien:

// __
// |__) .| _| _ _ _
// |__)|_|||(_| |||(_||_)
// |
function buildMap(b, w, h) {
}

// __
// |__)_ _ _ |
// | \(-\/(-(_||
function reveal(y, x) {
}

//--Of gewoon zoiets om even aan te geven dat dit heel ergens anders voor is
var komkommersalade;


Verder eigenlijk ook niet echt, is alleen maar extra typewerk, tog? :)

[Roenes]

Saphua ik hoop dat je opmerking van commentarieren en je stukje AS niet samenvallen :p

Want als dat je commentaar is, vind ik het eerlijk gezegd niet netter ;)

[TheDutch]

Het becommentariseren van code is extreem belangrijk, wanneer je gezamenlijk aan projecten werkt en er enorm veel sharing van code plaatsvindt. Op zich is het belangrijk om met je ontwikkelteam een commentaar standaard te verzinnen, zodat iedereen binnen een project exact dezelfde ideeen heeft bij becommentariseerde interfaces.
Ben het helemaal eens met wat kH_ hier heeft neergezet (ook daaronder alleen dan wordt het zo lang ;)).
Ik had het niet beter kunnen verwoorden! http://flash-forum.flashdevils.com/images/smilies/xyxthumbs.gif

[De Kale]

zie mijn post 'open source initiatief'... die zegt wel genoeg denk ik...

[Dopefish]

Laatst een flaatje gedownload en dat zag er ongeveer zo uit:


// ============================================
// ============================================
// ============================================
//
// NIETS VAN DEZE CODE MAG GEBRUIKT WORDEN
// ZONDER TOESTEMMING. © NAAM PERSOON
//
// ============================================
// ============================================
// Aan deze tutorial is veel aandacht besteed
// en het is niet de bedoeling om deze code
// klakkeloos te copieeren
// ============================================
// ============================================
// ============================================
gotoAndPlay(20);
// deze code zorgt ervoor dat u naar frame 20 gaat.

Commentaar is dus onnodig

wow dit is inderdaad wel extreme overkill.. en hij werkt niet eens met frame labels :p

[CodeCaster]

Whoei eerste post hier. Ik hoop veel te leren op deze site, en misschien (over een jaar ofzo, als ik het eindelijk snap) zelfs mensen te kunnen helpen.

Over code becommentariseren:

"Real programmers don't comment. Good code is hard to write, so it should be hard to read" is de onder programmeurs veel gebruikte signature op fora.

Uiteraard onzin, als je eindelijk weet hoe iets moet, zet je er graag even bij hoe je dat voor elkaar gekregen hebt, zodat je het later nog snapt ook ;-)

[SaphuA]

Saphua ik hoop dat je opmerking van commentarieren en je stukje AS niet samenvallen :p

Want als dat je commentaar is, vind ik het eerlijk gezegd niet netter ;)
Haha maar in Flash ziet het er wel cool uit :D
Bedoelde er eigenlijk mee te zeggen dat ik haast geen comments gebruik, alleen als ik weet dat ik na enkele maanden het project weer terug ga kijken. ;)

[LB Back]

Ik gebruik vaak commentaar om, met name voor mezelf, sneller door de code te kunnen scannen (beetje wat Pimm zegt) en vaak ook nog een logic vooraf te definieren als het om erg lange lappen code gaat.

In de logic vertel ik in 1 a 2 zinnen hoe de hele lap inelkaar steekt. Met tussendoorcommentaar scheidt ik groepen functies ed. Bijvoorbeeld buttonfuncties van kleurobjecten etc...

In fla's van anderen waar ik in moet werken zet ik vaak commentaar over waar ze op clipEvents of andere vage plekken code hebben verstopt als ik het daar niet kan weghalen.

[Fatty Owl]

ik becommentariseer(zo goed geschreven:p?) als ik aan een code bezig ben en ik ga van de computer. Want anders weet ik niet meer waar ik zat of welk probleem ik had ontdekt. Als de code af is haal ik die toch weg:p

[TrueChaoZ]

Om even een samenvatting te doen:
Het lijkt me duidelijk dat we hier te maken hebben met designer en developers (en alles wat daartussen valt reken ik toch tot designers ;) )
Designers becommentariseren haast nooit, alleen als ze het zelf echt nodig vinden en dan nog verwijderen ze het soms later weer.
Developers becommentariseren vrijwel altijd, en zien ook echt het nut ervan in (als documentatie voor anderen of voor jezelf als je het later nog eens wilt aanpassen of hergebruiken)
Iedereen ziet het nut er wel van in als er gewerkt wordt met een team, maar hierbij is het dan wel belangrijk dat je een standaard van commentaar-vorm afspreekt
Code zo duidelijk schrijven dat iedereen snapt wat het is, clear coding ofzoiets heet dat, is een illusie :O
Ik denk dat ik voor iedereen spreek als ik zeg dat het jammer is dat er nog geen commentaar-standaard in Flash ActionScript is meegenomen, zoiets als bijvoorbeeld JavaDoc. Hoewel een standaard niet altijd betekent dat iedereen het gebruikt.

[Tha Narie]

Code zo duidelijk schrijven dat iedereen snapt wat het is, clear coding ofzoiets heet dat, is een illusie :O

Is geen illusie, maar je moet het wel zo goed mogelijk nastreven. Geef variable- en functienamen gewoon duidelijke benamingen zodat je al weet wat het doet, en ga geen 1- of 2-letterige variables gebruiken!

[TrueChaoZ]

Is geen illusie, maar je moet het wel zo goed mogelijk nastreven. Geef variable- en functienamen gewoon duidelijke benamingen zodat je al weet wat het doet, en ga geen 1- of 2-letterige variables gebruiken!Het is inderdaad zeker handig om wel clear coding te gebruiken, ik wilde even een reactie uitlokken ;), maar het is iets wat je naast goede documentatie moet doen, en niet in plaats van IMO :)

[Dauntless]

Ik geef TrueChaoz zeker gelijk! Clear coding is iets dat elke developper zou moeten nastreven! Maar dat mag zeker niet de substituut van code becommentarisering zijn. Het is niet omdat je functie namen & var namen duidelijk zijn dat je weet hoe het nu echt gebeurt.

Maar zo'n battle als AS 400bytes is ook leuk om eens het volledig tegengestelde te doen :D.