Egy programozó milyen íratlan szabályokat tart be jegyzetelés közben?

Na, ott az lesz a nagy helyzet, hogy megmondják..

De egyébként ne ezzel kezdd, hanem mondjuk.. a programozással?

amúgy, csak hogy ne offoljak:

[link]

például ez elég gyakori

TILOS! Ha kommentelned kell, akkor az azt jelzi, hogy sz.r kódot írtál.

Olvasd el ezt: [link]

Utána világos lesz. Egyébként pedig örülök neki, hogy megkérdezted, mert híguló kis szakmánkban néha már jóformán az is csoda, ha valaki egyáltalán tudatában annak, hogy lehet írni jól átlátható, minőségi kódot is. Inkább taknyolnak, gányolnak, összesz_rják az egészet kommentekkel, aztán csodálkoznak, ha egy kompetensebb kolléga kijelenti, hogy a munkájuk egy fillért sem ér.

Oké, kicsit bővebben is:

A "mi ez" -re ott a JavaDoc/PHPDoc/AkármiDoc. Ebben leírod az API -t. Sem többet, sem kevesebbet.

Általános kommentnek akkor és csak akkor van helye a kódban, ha valami okból speciális megoldásra kényszerülsz. Ezesetben egy rövid kommentben meg kell említeni, miért. Ha azt írod le (amennyiben nem egyértelmű), hogy MIÉRT oldottad meg a feladatot úgy, ahogy, az elfogadható. Ellenben, ha azt kommenteled oda, hogy MIT csinál a kód, akkor az merénylet. Ezesetben a kód rossz.

#2 válaszadóval nem értek egyet, ill. részben csak.

A lényeg, hogy a kód natív és átlátható legyen, ez így van, de a kommentelést nem lehet tilossá tenni.

Én elég szép kódot gyártok, átláthatóan tagoltan programozok, mégis sok helyen kommentelem a munkámat. Egyészt mert többen is dolgozhatunk ugyanazon a projekten, másrészt pedig bizonyos helyeken szükséges a kommentelés. ilyen például egy osztály bemenő paramétereinek részletezése, vagy befejezetlen/bővítendő struktúra megjelölésére.

Az nyilván ostobaság ha valaki azt írja le egy kommentben, hogy mit csinál a kód.

Időnként a kód egyes részeinek szeparálásához is hasznos ha kommentben megjelölöm, hogy pl. inicializálás, végrehajtás, adatbekérés...

Hogy te milyen kommenteket használsz az rajtad múlik, a lényeg, hogy segítség legyen, és ne fölösleges töltelék pl. ez baromság: "holnap vennem kell 2 kiló kenyeret, meg felvágottat..." :)

Ha már kommentelés és íratlan szabályok:

[link]

Kommentelni minden kódot kell(ene), hiába írsz beszédes kódot és beszédes neveket, a metódusok elé mindenképpen hasznos és szükséges egy megfelelő leírás. (Doxygennel mellesleg ebből egész szép kis dokumentációt is lehet rögtön generálni.)

Én is beleolvastam a CleanCode-ba (sajnos időm egyelőre nem engedte, hogy végigolvassam), de ezzel az alapvetésével nem tudtam egyetérteni. Szerintem bizonyos határok felett felesleges új metódusokat létrehozni, _csak_ azért, hogy önleíró legyen a kód - cserébe meg keletkezik +20 1-2 soros metóduska, és emiatt válik nehezebben áttekinthetővé.

Persze a kommentnek is csak akkor van értelme, ha nem a kód emberi nyelven történő megfogalmazása, hanem inkább a szándékot, vagy valamilyen körülményt rögzít. Másik a metódusok/osztályok adott környezetben megszokott szintaktikájú kommentekkel való ellátása (itt is rögzítve, hogy egy-egy paraméterre milyen megkötéseket alkalmazol), ezzel a saját, illetve mások munkáját is nagyban segíted, illetve a későbbiekben kódgenerálásra is használhatod - csak ügyelj arra, hogy mindig aktuális legyen!

A kedvencem egyébként az aktualitását vesztő komment, amely jobb esetben csak "ballaszt", rosszabb esetben kifejezetten félrevezető...