it-swarm-eu.dev

"Komentáře jsou vůně kódu"

Můj spolupracovník věří, že jakékoli použití komentářů v kódu (tj. Nikoli metoda stylu javadoc nebo komentáře třídy) je vůně kódu) . Co myslíš?

100
Fishtoaster

Pouze pokud komentář popisuje, co kód dělá.

Pokud bych chtěl vědět, co se děje v metodě nebo bloku, přečetl bych kód. V každém případě doufám, že vývojáři, kteří pracují na daném projektu, byli alespoň dostatečně obeznámeni s vývojovým jazykem, aby si mohli přečíst, co je napsáno, a porozumět tomu, co dělá.

V některých případech extrémní optimalizace můžete použít techniky, které někomu ztěžují sledovat, co váš kód dělá. V těchto případech mohou a měly by být komentáře použity nejen k vysvětlení toho, proč máte takové optimalizace, ale co kód dělá. Dobrým pravidlem by bylo mít někoho jiného (nebo více dalších lidí) seznámit s implementačním jazykem a projektem, podívat se na váš kód - pokud nerozumí proč a jak, pak byste měli komentovat proč i jak.

Co však v kódu není jasné, je to, proč jste něco udělali. Pokud zvolíte přístup, který ostatním nemusí být zřejmý, měli byste mít komentář, který vysvětluje, proč jste učinili rozhodnutí, která jste udělali. Mám podezření, že si možná ani neuvědomíte, že je potřeba komentář, až po něčem, jako je kontrola kódu, kde lidé chtějí vědět, proč jste místo X místo Y - můžete zachytit svou odpověď v kódu pro všechny ostatní, kteří se na to dívají v budoucnu.

Nejdůležitější však je změnit vaše komentáře, když změníte kód. Pokud změníte algoritmus, nezapomeňte aktualizovat komentáře s tím, proč jste s algoritmem X přešli přes Y. Zastaralé komentáře jsou ještě větší vůní kódu.

167
Thomas Owens

To je obzvláště dráždivé, když v tuto chvíli slyším, tento víkend jsem strávil nějaký čas zkoumáním velmi dobře pojmenovaného, ​​velmi čistého, nekomentovaného kódu implementujícího výzkumný algoritmus (ten, který ve skutečnosti není zveřejněn). Jsem s tím na vysoké úrovni obeznámen, ten chlap, který seděl vedle mě, byl vynálezcem a kód napsal před několika lety někdo jiný. Mohli bychom stěží následovat.

Váš spolupracovník samozřejmě není dostatečně zkušený.

110
Paul Nathan

Komentáře by měly vysvětlit proč, ne jak.

Poznámky typu How se obvykle lépe řeší pomocí refaktoringu. Osobně se obvykle vyhýbám komentářům ve prospěch refaktoringu.

Před:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

po:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)
75
Sam Saffron

Prohlašuji tvého spolupracovníka za kacíře! Kde jsou moje kacířské boty?

Obsedantní komentování je špatné a bolest hlavy údržby a komentáře nenahrazují dobře pojmenované metody, třídy, proměnné atd. Ale někdy uvádějí proč něco je způsob, jak to může být nesmírně cenné pro chudého idiota, který musí udržovat kód do šesti měsíců - zejména když se ten chudý idiot ukončí tím, že jste vy.

Některé skutečné komentáře z kódu, na kterém pracuji:


    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

32
BlairHippo

V ideálním případě by kód měl být tak dobře kódován, že by měl být automaticky vysvětlující. Ve skutečném světě víme, že i velmi kvalitní kód musí někdy komentovat.

Absolutně byste se měli vyhnout „redundanci kódu komentáře“ (komentáře, které do kódu nic nepřidávají):

i++; // Increment i by 1

Pokud tedy existuje dobrý (a udržovaný/zarovnaný) návrh kódu a dokumentace, je komentář méně užitečný.

Za určitých okolností však mohou být komentáře dobrou čitelností při čtení kódu:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Nezapomeňte, že musíte udržovat a udržovat synchronizaci také komentáře ... zastaralé nebo nesprávné komentáře mohou být strašlivou bolestí! A obecně je příliš mnoho komentářů příznakem špatného programování.

29
Wizard79

Kategoricky definující metodu nebo proces jako „zápach kódu“ je „zápach horlivosti“. Tento termín se stává novým „považovaným za škodlivý“.

Pamatujte, že všechny tyto věci by měly být vodítkem.

Mnoho dalších odpovědí poskytuje dobré rady ohledně toho, kdy jsou komentáře odůvodněné.

Osobně používám jen velmi málo komentářů. Vysvětlete účel neobvyklých procesů a občasné ohrožení smrtí nechte na kohokoli, kdo by mohl uvažovat o změnách věcí sám o sobě, které vyžadovaly týdny ladění.

Refaktoring všeho, dokud mateřská škola nechápe, že to pravděpodobně není efektivní využití vašeho času, a pravděpodobně nebude fungovat tak dobře jako stručná verze.

Komentáře nemají vliv na dobu běhu, takže jediným negativním problémem, který je třeba zvážit, je údržba.

26
Bill

Primárním problémem je zde význam pojmu „vůně kódu“.

Mnoho lidí (včetně vás, myslím) chápe vůni kódu jako něco podobného chybě nebo alespoň něčemu, co je třeba opravit. Možná si to myslíte jako synonymum pro „anti-pattern“.

Toto není význam termínu!

Metafora vůně kódu pochází z Wards Wiki a zdůrazňují:

Všimněte si, že CodeSmell je náznak, že by něco mohlo být špatně, ne jistota. Dokonale dobrý idiom může být považován za CodeSmell, protože je často zneužíván, nebo proto, že ve většině případů funguje jednodušší alternativa. Volání něco, co CodeSmell není útokem; je to prostě známka toho, že je třeba se blíže podívat.

Co to znamená, že komentáře jsou vůně kódu: to znamená, že když uvidíte komentář, měli byste se zastavit a myslet si: „Hmmm, cítím náznak, že by se něco mohlo zlepšit“. Možná můžete proměnnou přejmenovat, provést „extrakční metodu“ - opravu - nebo možná je komentář tím nejlepším řešením.

To je to, co znamená, že komentáře jsou vůně kódu.

EDIT: Právě jsem narazil na tyto dva články, které to vysvětlují lépe než já:

23
Rasmus Faber

V některých případech nemůže komentář nahradit žádné množství dobrého pojmenování, refaktoringu atd. Stačí se podívat na tento příklad v reálném světě (jazyk je Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Vypadá to divně, že? Pravděpodobně chyba kopírování a vložení? Pláče za opravu chyby?

Nyní to samé s komentáři:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
23
user281377

Myslím, že pravidlo je docela jednoduché: představte si, že váš kód vidí úplně cizinec. Asi za 5 let budete pravděpodobně cizincem svého vlastního kódu. Pokuste se minimalizovat mentální úsilí, abyste pochopili váš kód pro tohoto cizince.

21

Dobrým nápadem mít správné komentáře je začít psát komentáře.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

To vám umožní snadno extrahovat metody a zbavit se komentářů,
jen ať to kód pověří! Podívejte se, jak je to přepsáno (vyjmuto/vloženo) velmi pěkným způsobem:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

U věcí, které nelze oddělit, nevytahujte metody a do poznámek zadejte kód.

To je to, co považuji za užitečný způsob, jak udržovat komentáře na minimu, je opravdu zbytečné jít komentovat každý řádek ... Dokumentovat pouze jeden řádek, pokud jde o inicializaci magické hodnoty nebo tam, kde to dává smysl.

Pokud jsou parametry použity příliš mnoho, pak by měly být soukromými členy ve vaší třídě.

11
Tamara Wijsman

Myslím, že odpověď je obvyklá „záleží“. Komentování kódu pouze pro komentář je vůně. Komentování kódu, protože používáte obskurní algoritmus, který je o řád rychlejší, uloží programátorům údržby (obvykle mě 6 měsíců poté, co jsem jej napsal) půl dne prohrabáváním kódu, aby určil, co dělá.

10
Brandon
// Dear me in the future. Please, resolve this problem.

nebo

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.
10
Zzz

Poznámky k kódu rozhodně nejsou „vůní kódu“. Tato víra obvykle vychází ze skutečnosti, že komentáře se mohou stát zastaralými (zastaralými) a je obtížné je udržovat. Mít dobré komentáře, které vysvětlují, proč kód dělá něco určitým způsobem, může (a obvykle je) důležité pro údržbu.

Dobré komentáře usnadňují pochopení toho, co kód dělá, a co je důležitější, proč to dělá zvláštním způsobem. Komentáře by měly být čteny programátory a měly by být jasné a přesné. Komentář, který je těžko srozumitelný nebo nesprávný, není o nic lepší, než mít žádný komentář.

Přidání jasných a přesných komentářů do kódu znamená, že nemusíte spoléhat na paměť, abyste pochopili „co“ a „proč“ části kódu. To je nejdůležitější, když se na tento kód podíváte později, nebo někdo jiný se na váš kód musí podívat. Protože se komentáře stávají součástí textového obsahu vašeho kódu, měly by se kromě jasně psaného textu řídit zásadami dobrého psaní.

Chcete-li napsat dobrý komentář, měli byste se co nejvíce snažit zdokumentovat účel kódu (proč, ne jak) a co nejjasněji uvést důvody a logiku za kódem. V ideálním případě by poznámky měly být psány současně s tím, jak píšete kód. Pokud budete čekat, pravděpodobně se už nevrátíte a nepřidáte je.

Sams Učte se Visual C # 2010 za 24 hodin , str. 348-349.

8
Scott Dorman

Pokud byl kód napsán určitým způsobem, aby se předešlo problému v knihovně (knihovna třetích stran nebo knihovna dodávaná s kompilátorem), má smysl jej komentovat.
Také má smysl komentovat kód, který je třeba změnit v budoucích verzích, při použití nové verze knihovny nebo při přechodu například z PHP4 na PHP5.

6
kiamlaluno

Dokonce i ta dobře napsaná kniha má stále pravděpodobně úvod a názvy kapitol. Komentáře v dobře zdokumentovaném kódu jsou stále užitečné pro popis konceptů na vysoké úrovni a pro vysvětlení, jak je kód organizován.

6
munificent

Čestné uznání je anti-vzor:

Mám dojem, že někdy se často používají preambule licencí FLOSS místo dokumentace k souboru. GPL/BSDL vytvoří pěkný výplňový text a poté jen zřídka uvidíte jakýkoli další blok komentářů.

4
mario

Nesouhlasím s myšlenkou, že psaní komentářů k vysvětlení kódu je špatné. To zcela ignoruje skutečnost, že kód obsahuje chyby. Může být jasné, jaký kód dělá bez komentářů. Je méně pravděpodobné, že bude jasné, co bude kód předpokládat dělat. Jak víte, jestli jsou výsledky nesprávné nebo pokud jsou použity nesprávně?

Komentáře by měly vysvětlit úmysl kódu, takže pokud dojde k chybě, někdo, kdo si přečte komentáře + kód, má šanci jej najít.

Obecně se mi zdá, že píšu vložené komentáře dříve Píšu kód. Tímto způsobem je jasné, co se snažím napsat kód, a omezuje ztrátu algoritmu, aniž bych věděl, co se snažíte udělat.

4
Danny Tuppeny

Odpovím na svou vlastní otázku. Můžete najít chybu v nekomprimovaném kódu níže?

tl; dr: Další osoba, která bude udržovat váš kód, nemusí být tak božská jako vy.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_Push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  Push ax
  add bx, 1
  add cx, 1
  jmp strreverse_Push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55
3
Ant

Komentáře, které jsou vloženy, protože si někdo myslí, že je v pořádku mít 700 řádků v jedné metodě, jsou vůně.

Komentáře, které jsou tam proto, že víte, pokud nemáte komentář, někdo udělá stejnou chybu znovu, jsou vůně.

Komentáře vložené, protože nějaký nástroj pro analýzu kódu vyžaduje, aby to byl také zápach.

Lidé, kteří nebudou někdy přidávat komentáře, nebo psát i malou pomoc ostatním vývojářům, jsou také vůni. Jsem ohromen tím, kolik lidí nebude psát věci, ale pak se otočí a uzná, že si nepamatují, co udělali před 3 měsíci. Nelíbí se mi psaní dokumentů, ale rád bych lidem říkal totéž znovu a znovu, ještě méně.

3
MIA

Musíte udržovat rovnováhu mezi kódem a komentáři ... Obvykle se snažím přidat nějaké komentáře, které obnoví blok kódu. Ne proto, že nebudu schopen porozumět kódu (dobře, to také), ale proto, že dokážu číst rychleji svůj vlastní kód a lokalizovat konkrétní sekce, kde se děje důležité věci.

Mimochodem, moje osobní kritéria jsou „v případě pochybností, komentář“. Raději mám nadbytečnou linii než úplně kryptickou linii, které nebudu schopen pochopit. Vždy mohu odstranit komentáře ke kontrole kódu, po chvíli (a obvykle to dělám)

Také komentáře jsou velmi užitečné při přidávání „upozornění“, například „Buďte opatrní! Pokud formát vstupu není ASCII, bude se muset tento kód změnit!“

2
Khelben

Myslím, že kódování komentářů začíná velmi špatným začátkem života. Nevím o těchto dnech, ale když jsem se poprvé učil programování ve škole, dostal jsem úkoly typu „Napište program, který vytiskne čísla jedna až deset na samostatné řádky. Nezapomeňte svůj kód komentovat.“ Pokud byste nepřidali komentáře, dostali byste označení, protože komentování kódu je DOBRÁ VĚC.

Ale co se dá říci o takovém triviálním procesu? Takže skončíte psaní klasiky

i++; // add one to the "i" counter.

jen proto, abyste získali slušnou známku a pokud jste vůbec žádní, okamžitě vytvořte velmi nízký názor na kódové komentáře.

Komentář k kódu není DOBRÁ VĚC. Je to NEDOSTATNÁ VĚC SOMETIMES a Thomas Owens v hlavní odpovědi poskytuje vynikající vysvětlení situací, ve kterých je to nutné. Tyto situace se však zřídka objevují v domácích úkolech.

V mnoha ohledech by přidání komentáře mělo být považováno za poslední možnost, když to, co je třeba říci, nelze jasně říci v aktivních částech programovacího jazyka. Ačkoli pojmenování objektů může být zastaralé, různé mechanismy nedostatečné zpětné vazby u lidí a počítačů usnadňují zapomínání na udržování komentářů, a proto komentáře stagnují mnohem rychleji než aktivní kód. Z tohoto důvodu by měla být vždy upřednostňována změna kódu, aby byla jasnější, než anotace nejasného kódu poznámkami.

2
Alohci

Když jsem si to přečetl, připomněl jsem si něco, co jsem poprvé přečetl (z delšího seznamu, uchovaného fotokopiemi) o několik desítek let zpět:

Skuteční programátoři nepíšou komentáře - pokud by bylo těžké napsat, mělo by být obtížné si je přečíst

Poněkud starší vůně.

2
Murph

Komentáře samozřejmě jsou vůně kódu ...

každý programátor ví, že jsme všichni nakonec zase šílený kvůli množství práce, ladění nebo prostému šílenství, na které narazíme.

"Udělej tohle!" říká váš projektový manažer.

Odpovíte: „To se nedá udělat.“

Říkají: „Pak najdeme někoho jiného, ​​aby to udělal.“

Říkáte: „Dobře, možná se to dá udělat.“

A pak strávit dalších X počet dní .. týdnů .. měsíců .. snaží se to přijít. V průběhu celého procesu se budete snažit selhat a pokusit se selhat. Všichni to děláme Pravá odpověď je, že existují dva typy programátorů, ti, kteří komentují, a ti, kteří to ne.

1) Ti, kteří to dělají, buď usnadňují svou vlastní práci tím, že dokumentují pro budoucí použití, komentují neúspěšné rutiny, které nefungovaly (zápach je neodstraňuje po nalezení toho, který funguje), nebo rozdělí kód s komentářem formátování doufejme usnadní čtení a porozumění. Vážně je nemůžu obviňovat. Nakonec ale uchopí a pak máte toto: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Ti, kteří předstírají, že nejsou superhrdinou, nebo žijí v jeskyni . Prostě bezohledně ignorují ostatní, samy sebe a mohou se o kód méně zajímat, nebo o jaký význam to může mít později.

Teď mi nedělej špatně .. samokokumentující proměnné a funkce tomu mohou úplně zabránit .. věř mi nikdy nemůžete udělat dost vyčistění kódu. Ale jednoduchá pravda je, že pokud si budete zálohovat, můžete [~ # ~] vždy [~ # ~] mazat komentáře.

1
Talvi Watia

Mezi komentářem a kódem je velký zásadní rozdíl: komentáře jsou způsob, jak lidé sdělují nápady jiným lidem, zatímco kód je určen především pro počítač. V „kódu“ je mnoho aspektů, které jsou také pouze pro lidi, jako je pojmenování a odsazení. Ale komentáře jsou psány výhradně pro lidi, lidmi.

Psaní komentářů je proto stejně obtížné jako jakákoli písemná lidská komunikace! Spisovatel by měl mít jasnou představu o tom, kdo je publikum a jaký text bude potřebovat. Jak můžete vědět, kdo bude číst vaše komentáře za deset, dvacet let? Co když je osoba z úplně jiné kultury? Atd. Doufám, že to všichni chápou.

Dokonce i v malé homogenní kultuře, ve které žiji, je tak těžké sdělovat myšlenky jiným lidem. Lidská komunikace obvykle selže, s výjimkou nehody.

1
user15127

Řekl bych, že nepoužívání některých komentářů ve vašem kódu je vůně kódu. I když souhlasím s tím, že kód by se měl co nejvíce samodokumentovat, narazíte na určitý bod, kde uvidíte kód, který nedává smysl bez ohledu na to, jak dobře je kód napsán. Viděl jsem nějaký kód v obchodních aplikacích, kde jsou komentáře do značné míry povinné, protože:

  1. Musíte udělat něco od případu k případu a neexistuje žádná dobrá logika.
  2. Kód se pravděpodobně změní za rok nebo dva, když se změní zákony a chcete je rychle najít.
  3. Někdo v minulosti upravoval kód, protože nerozuměl tomu, co kód dělá.

Také průvodce stylem společnosti vám může říci, že byste měli udělat něco určitým způsobem - pokud říkají, že by váš mohl obsahovat komentáře, které blokují kód ve funkci, přidejte komentáře.

1
rjzii

Musím souhlasit s tvým spolupracovníkem. Vždy říkám, že když svůj kód okomentuji, znamená to, že se obávám, že I nebudu schopen přijít na to můj vlastní kód v budoucnu. To je špatné znamení.

Jediným dalším důvodem, proč posypu komentáře do kódu, je vyvolání něčeho, co se nezdá být rozumné.

Tyto komentáře mají obvykle podobu:

//xxx what the heck is this doing??

nebo

// removed in version 2.0, but back for 2.1, now I'm taking out again
0
Ken

Tady je moje pravidlo:

  • Napište kód a krátké shrnutí kódu uložte do samostatného dokumentu.
  • Nechte kód několik dní na pokoji, abyste mohli pracovat na něčem jiném.
  • Návrat na kód. Pokud nemůžete okamžitě pochopit, co má dělat, přidejte shrnutí do zdrojového souboru.
0
Maxpm

Poučte svého spolupracovníka o technice Literate Programming .

0
SK-logic

Poznámky k kódu, které případně obsahují argumenty a návraty funkcí, pole struktury, dokonce i lokální proměnné, mohou být velmi užitečné. Pamatujte na Mars Orbiter!

0
dmuir

Ne, komentáře nejsou vůní kódu, jsou pouze nástrojem, který lze zneužít.

Příklady dobrých komentářů:

// Myslím, že je to v cm. Je nutné další vyšetřování!

// Toto je chytrý způsob, jak dělat X

// Zde je zaručeno, že seznam není prázdný

0
Andres F.

Nicméně kód, kterému vůbec nelze rozumět, to hodně větší vůně kódu ...

Prosím, dejte mi čistý kód, na kterém se budu zabývat
Pokud to není možnost, měl bych raději „špinavý“ kód s komentáři
než špinavý kód bez komentářů.

0
Ian

Většina slov byla vyňata z mých úst. Ale předpokládám, že to shrnu všechno: smyslem komentářů je poskytnout popis/vysvětlení toho, co kód dělá.

Dále uvádíme několik příkladů, jak používám komentáře:

  • jako nadpisy, k označení obecného účelu části kódu
  • abych si všiml, odkud jsem kód rozdával a vyhnul se plagiátorství
  • občas na konci bloků, abych připomněl, o jaký blok jde
  • poukazovat na to, že kód, který může vypadat podezřele, je zamýšlený (např. ty liché časy, kdy dojde k přepnutí případu přepínače)
  • vysvětlit matematiku za algoritmem
0
Stewart

Nikdo to zatím v tomto vláknu neřekl, takže budu:

Názvy typů, názvy proměnných, názvy funkcí, názvy metod a komentáře jsou pouze metadaty o vašem kódu a nemají nic společného s strojovým kódem, který kompilátor generuje (samozřejmě kromě názvů exportovaných a ladících symbolů).

Názvy typů a názvy proměnných jsou vaše podstatná jména, názvy funkcí a metod jsou vaše slovesa, pomocí kterých popíšete kroky, které je třeba provést. Komentáře jsou pro všechno ostatní.

Nějaké příklady:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

Komentáře se mohou stát zastaralými, pokud nejsou aktualizovány, ale názvy proměnných a funkcí se mohou také stát zastaralými. Nedávno jsem narazil na pole bufPtr ve struktuře C, které nemá nic společného s buffery nebo ukazateli. A viděl jsem funkci inflateBuffer, která nedekomprimuje vypuštěná data, ale kompletní soubor GZIP ... To jsou nepříjemné jako zastaralé komentáře.

0
Calmarius

Nezdá se, že příliš mnoho odpovědí zvažuje programování v týmech. Jsem senior vývojář a mám tendenci psát komentáře zaměřené na vysvětlení toho, co je jinak pro mě jednoduché pochopit.

Vidím to jako formu posmrtné týmové komunikace nebo vzdělávání. Doporučuji týmu, aby prozkoumal kód, který používají, ale možná není napsán, aby mu lépe porozuměl.

Několik příkladů právě z tohoto týdne (PHP kód):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

Doufám, že jméno PATTERN_PHOTO bylo by užitečné později v kódu vysvětlit, co to dělá, ale bez komentářů, jak jasné by bylo juniorskému vývojáři, co tento konkrétní vzorec dělá?

Stejná sada kódu:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

Očekávají se, že naši vývojáři znají PHP, ale ne že rozumí operačnímu systému Linux, který používáme pro hostování.

Zjistil jsem tedy, že tyto komentáře skutečně zvyšují celkovou efektivitu našeho týmu za velmi krátkou dobu, než je napsat.

  • Je méně případů, kdy lidé přepisují kód jednoduše proto, že nechápou, jak to funguje. "Nechápal jsem, jak to dělá, co má, tak jsem to opravil." Vážně jsem se s tím musel vypořádat dříve.
  • Na jednotlivé kusy kódu je kladeno méně otázek. Odpověď na otázky pouze jednou obvykle vyžaduje vyhledání kódu a čas, abych se s ním znovu seznámil. A někdy dostanu stejnou otázku z více než jedné osoby od sebe. (Ano, bylo by to ve věcech tak jednoduchých jako výše uvedené příklady)
  • Ostatní vývojáři jsou povzbuzováni a vedeni, aby se učili sami. Očekával bych, že kdyby narazili na //Ignore . and .. directories in Linux pravděpodobně by naskočili na Google a najednou by pochopili Linux trochu lépe.
0
Chris