it-swarm-eu.dev

Vlastní dokumentační kód Vs. Komentovaný kód

Hledal jsem, ale nenašel jsem, co jsem hledal. Pokud již byla tato otázka položena, neváhejte a propojte mě.

Začátkem tohoto měsíce byl tento příspěvek vytvořen:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Zjednodušeně řečeno, jste špatný programátor, pokud nepíšete komentáře. Můj osobní názor je, že kód by měl být popisný a většinou by neměl vyžadovat komentáře, pokud tento kód nemůže být sám popisující.

V uvedeném příkladu

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Autor řekl, že tento kód by měl být komentován, můj osobní názor je, že kód by měl být funkční volání, které je popisné:

$extension = GetFileExtension($image_filename);

V komentářích však někdo skutečně navrhl:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-3571

Autor odpověděl, že komentátor byl „jedním z těch lidí“, tj. Špatným programátorem.

Jaké jsou názory elfů na kód popisující samy sebe a komentáře?

22
Phill

Dávám přednost psaní samokumentujícího kódu. Příručka je Čistý kód .

To samozřejmě neznamená, že byste nikdy neměli používat komentáře - mají svou roli, ale IMHO byste je měli používat opatrně. Tato dřívější odpověď na SO vysvětluje mé myšlenky na toto téma podrobněji.

Samozřejmě, jak poznamenal @ Niphra, vždy stojí za to dvakrát zkontrolovat, že to, co považuji za čisté, je ostatním opravdu pochopitelné. To je však také otázka praxe. Zpět do uni jsem psal kryptické kousky kódu jednoduše kvůli použití podivných a vtipných jmen pro všechny kódové entity, podle mého rozmaru. Dokud můj učitel nevrátil jedno z mých úkolů, zdvořile si všiml, že nedokáže zjistit, který modul byl hlavní :-) To byla dobrá lekce, a od té doby jsem se snažil soustředit na psaní čitelnějšího kódu. V současné době těžko dostávám stížnosti od spoluhráčů.

47
Péter Török

Neměli byste dokumentovat, co kód dělá, ale měli byste dokumentovat, proč to dělá.

Žádné množství pojmenování trik nebude vystavit whys a proč, takže musíte přidat komentáře vysvětlit účel různých bitů kódu.

Všechny ostatní komentáře se mohou bezpečně zbavit.

66
biziclop

Ve skutečnosti nevěřím self-description code. Existuje více čitelný kód a méně čitelný kód, v závislosti na jazyce, vašich znalostech o tom (jako původní autor), znalost toho, kdo ho četl, a funkce kódu. Ale ne, pořád ... mělo by být popsáno krátkým komentářem.

Co je mi teď jasné, že jsem v v této oblasti myšlení mi to asi nebude jasné za rok, když přemýšlím o něčem úplně jiném a potřebuji tuto část použít kód znovu.

Takže komentujte svůj kód. Ne každý řádek (dobrá nebe, ne) samozřejmě, ale vložte několik řádků komentáře nad funkce/podprogram/modul, nebo zvláště ošidnou část a krátce řekněte, co to dělá. Za rok nebo dva se vám poděkuje.

38
Rook

Naštěstí jsou zde zastoupeny oba tábory v této diskusi a pro oba byly zmíněny argumenty pro a proti.

Věřím, že oba tábory mají překrývající se argumenty, a ve skutečnosti se na většině z nich shoduji, jen způsob, jak jich dosáhnout, je trochu jiný.

Překrývající se argumenty

  • Kód by měl být čitelný.
  • Komentáře by neměly říkat přesně to samé jako kód, ale v případě potřeby by měly poskytnout další informace.
  • Všechny názvy proměnných/funkcí by měly být dobře promyšleny, aby poskytovaly dobrou představu o tom, co jsou/dělají.
  • Je třeba zabránit duplicitnímu kódu.

Nyní je hlavní rozdíl v tom, jak velkou váhu mají některé z těchto argumentů.

Samopopisující kód

  • Komentáře mohou být zastaralé, takže je můžete minimalizovat, protože nesprávné komentáře jsou horší než žádné komentáře.
  • Komentáře jsou duplikátem kódu. Vše, co lze napsat v kódu, by mělo být napsáno v kódu.

Další komentáře

  • Komentáře jsou čitelnější než kód. Obyčejná angličtina lépe popisuje něco.

  • Obyčejný kód často způsobuje dvojznačnost, kterou je třeba stejně komentovat. Výsledkem pokusu popsat kód v kódu jsou příliš dlouhá jména. Kromě toho jste neustále konfrontováni s těmito „extra“ informacemi, které potřebujete pouze při prvním setkání s nimi.

Věřím, že oba tábory mají velmi platné argumenty, ale neměli byste zoufale následovat jeden tábor, jen proto, že řeší jeden problém.

Abychom demonstrovali v knize Čistý kód , je kód rozdělen do četných menších metod, které se nazývají pouze jednou. Metody jsou vytvářeny z jediného důvodu k dokumentování kódu (a snadnějšího TDD). Výsledkem bude Function Hell . Kód je méně čitelný, než byl původně, a při refaktoringu nebylo uvažováno o zapouzdření opakovaně použitelného kódu.

Na druhé straně často vidíte API, kde jsou komentovány všechny funkce, jen proto, že „komentáře jsou dobré“. Věci, které měly být komentovány, stále nejsou.

19
Steven Jeuris

"Je mi líto, ale váš chlap."

Zajímalo by mě, proč nemá rád komentáře: P

Vážně, kódování je příliš mnoho umění, které by člověk mohl pravdivě učinit takovým velkým závěrem. Někdy potřebujete komentáře, někdy více a lépe pojmenované funkce. Obvykle obojí.

Podívejte se na gramotné programování jako na extrémní styl.

5
vegai

Krátká, lepší a správná odpověď

Myšlenka, že dobře napsaný „samodokumentovaný kód“ je vše, co potřebujete, je anti-vzor a měl by umřít, sudý, když udělá výjimky pro komentáře, které vysvětlují „proč“. Je to mýtus, že vždy můžete napsat veškerý kód pro jakýkoli algoritmus dostatečně jasný, aby na něj programátor mohl nahlédnout a získat jej (nebo že to nebude vyžadovat refaktoring ani organizační čas, který nemáte). Ještě důležitější je, častěji než ne, programátoři, kteří přemýšlejí píší jasný kód, ne.

Mnohem lepší odpověď než komentáře by měly být použity pouze k vysvětlení "proč" je, že komentáře by měly:

  • vysvětlit "proč" (samozřejmě)
  • vysvětlete „co“ na jednotlivých řádcích, pouze pokud je kód složitý nebo účel není jasný a nelze jej dále zjednodušit ani nestojí za to
  • vysvětlete „co“ pro bloky kódu pro urychlení porozumění a nalezení toho, co potřebujete

Vysvětlení pro zálohování

Lidé si chybně myslí, že jediným důvodem, proč lidé používají komentáře, je vysvětlit, co znamená řádek kódu. Pravda je velkým účelem komentování kódu, aby bylo rychlejší prohlédnout si kód a najít to, co hledáte. Když se později vrátím ke kódu nebo si přečtu kód někoho jiného, ​​mohu si přečíst a porozumět části dobře napsaného kódu - ale není rychlejší a snadnější přečíst komentář v horní části a říci, co tato část kódu dělá a přeskočit to úplně, pokud to není to, co hledám? Proč tam sedět a zjistit kód vůbec, i když je dobře napsaný, pokud se můžete podívat na pár komentářů a porozumět celé funkci? Proto pro funkce používáme popisná jména - nikdo neříká, že pro svou funkci nemusím používat popisné jméno, protože někdo může jen prostudovat můj čistě napsaný kód, aby viděl, co dělá.

Například, když se dívám na funkci někoho jiného, ​​je snazší projít řádek po řádku kódem, abyste viděli, co dělá, nebo se podívat na tři dobře napsané komentáře v celé funkci, abyste přesně viděli, co funkce dělá a kde dělá to?

Dalším anti-vzorem je nadužívání funkcí pro komentování vašeho kódu. Dobře pojmenované funkce jsou důležitou součástí dokumentace k kódu, ale někdy programátoři oddělují 2-3 řádky kódu, které nikdy nebudou použity nikde jinde na funkci pro účely dokumentace. Proč je nadužívání funkcí lepší než nadužívání komentářů? Používání takových funkcí je stejné jako přijímání příkazů GOTO - vytváří to špagetový kód, který může být bolest následovat.

V zásadě, když pracujete v podnikovém prostředí, kde lidé neustále sdílejí kód a lidé nemají vždy čas na zdokonalení kódu, může několik dobrých komentářů ušetřit spoustu času a frustrace. A pamatujte, že i když jste guru, který umí číst kód lehkou rychlostí, ne každý ve vaší kanceláři je pravděpodobně.

3
dallin

Dobře si také musíte pamatovat na něco, co je pro vás samozřejmé nebo „samokumentující“, nemusí být pro někoho jiného ... Možná někoho s menším porozuměním určitých funkcí. Takže komentuji téměř všechno.

2
user6791

Věc se samokumentujícím kódem je, že v rámci této funkce byste našli:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

což je samozřejmé, pokud máte název funkce, protože se jedná pouze o dva řádky. Když se věci komplikují, musíte buď zabalit každých pár řádků kódu funkcí popisným jménem, ​​nebo použít komentáře je-li to nutné.

Nikdy jsem nechápala, proč by to měla být a/nebo záležitost, místo a/a. Ano, vytvořte si co nejvíce samokumentujících dokumentů a ano, k částem přidejte několik komentářů, které by jinak byly poněkud nejasné.

2
Joris Meys

Komentáře a samokumentovaný čistý kód se liší. Kód je o jak dělat věci. A komentáře by měly zahrnovat část proč, kterou nelze vysvětlit kódem, ať už je váš jazyk jakýkoli. Pokud je váš jazyk velmi omezený a nemáte žádné smlouvy, žádné statické specifikace a dokonce ani tvrzení, komentáře by se měly vztahovat k problémům s hranicemi vašeho kódu.

2
SK-logic

V takovém případě je snadné vytvořit popisnou funkci. Ale četl jsem spoustu kódu od dobrých programátorů, kteří věřili, že jejich kód je samokumentující, a to, co jim bylo křišťálově jasné, pro mě bylo opravdu matoucí.

$ extension = GetFileExtension ($ image_name);

Abych se vrátil ke svému příkladu, mohu mu poslat řadu názvů obrázků, nebo to vezme jen jeden obrázek? Podporuje všechny typy souborů nebo jen některé z nich? Zajistí mi řetězec, nebo to musím udělat? Pokud typ souboru neexistuje, upozorní mě na to?

Tahle samozřejmě samozřejmě natahuji. Ale pamatuji si, že programátor, který věřil, že audio_bandwidth a video_bandwidth jsou samokumentující jména; Ukázalo se, že zvuk musí být vyjádřen v bajtech a video v kilobajtech. Trvalo hodně času, abych na to přišel.

1
DistantEcho

Jeden nevylučuje druhý. Přestože je váš kód komentován vlastními silami, mohou se vyskytnout případy, kdy budete potřebovat pravidelné komentáře, abyste vysvětlili proč váš vlastní komentář přiděluje, co dělá.

1
gablin

Nesouhlasím s tímto článkem a do jisté míry s vámi souhlasím. Pokud používáte dobré názvy metod, dobré názvy proměnných a malé metody, které dělají jednu věc, měl by být kód snadno sledovatelný.

Snažte se být chytrý, protože chytrý kód je hrozné čtení a údržba. Klíčové slovo: držovat!

Můj názor je, že komentáře by měly popisovat proč a ne co. Pamatujte si, že v tomto hypotetickém dokonalém světě je váš kód dostatečně čistý, aby umožňoval snadné čtení, nemusíte vysvětlovat, co dělá, ale proč jste se rozhodli to udělat tak či onak.

Pokud používáte systém řízení zdroje, můžete pomocí zprávy o potvrzení informovat všechny (a sebe), co jste dělali v daném čase, a co je důležitější, proč.

1
Sergio

Myslím, že musíme rozlišovat mezi dokumentací a expresivitou kódu.

Při ladění nebo kontrole kódu nečtete knihu. Většinu času chcete pouze přejít z metody na metodu a vytvořit si ve své mysli rychlá spojení, abyste získali základní představu o tom, co se děje za běhu. V tomto procesu nezáleží na dokumentování kolem kódu, ale na expresivitě podpisů kódu, jejich schopnosti být smysluplné stačí je okamžitě identifikovat a přidat je do svého vlastního interního zásobníku volání. V tu chvíli náš mozek (alespoň můj funguje takhle;)) má sklon považovat velké bloky komentářů spíše za hluk než za pomoc. Proto zde postačují jednořádkové komentáře, nebo ještě lépe, jen samy popisné metody a názvy objektů.

Pokud chcete „číst knihu“ určité třídy nebo funkce, je mnohem lepší místo v testech jednotek. Dobře navržené jednotkové testy od přírody odhalují záměry a mnohem více dokumentující (tj. Vysvětlující, podrobné) než nejsilnější z Bloky pro komentáře, protože obsahují 1/očekávání přesně toho, co má tento kód dělat, a 2/schopnost zkontrolovat tato očekávání s reálným kódem. Úspěšný test je stokrát spolehlivější než jakýkoli komentář z hlediska dokumentace, protože prokazuje, že to, co tvrdí, je pravdivé.

1
guillaume31

Nějaký kód prostě není zdokumentován a vyžaduje nějaký komentář od člověka, který tento kus pochopil a testoval. To, co mám níže, prostě nestačí, abych tomu rozuměl.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}
1
Job

Obecně dávám přednost psaní samodokumentujícího kódu s poznámkami, kde není jasné, protože si myslím, že většina kódu nebude sama dokumentovat úplně.

1
Abbafei

Chtěli byste se vyhnout psaní komentářů, stejně jako byste se chtěli vyhnout jakékoli dokumentaci. Pokud jde o samotný programovací jazyk, každý pracuje ze stejné sady slovní zásoby a syntaxe (téměř).

Pokud je vaše aplikace určena pro konkrétní doménu, může být obtížné přimět všechny, aby se dohodli a/nebo vytvořili společnou slovní zásobu. Naučili jsme se vyhýbat se zkratkám a rozsáhlému žargonu, ale budu tomu říkat

EBITDA

a ne

MajetekBeforeInterestTaxesDeprecationAndAmortization

Pokud jeden neznáte, pravděpodobně tomu druhému nerozumíte. Pokud má společnost nějakou neobvyklou implementaci, komentář by pomohl dalšímu programátorovi, který může mít zkušenosti s doménou, ale ne této konkrétní firmě (což jen komplikuje věci.).

1
JeffO

Komentáře jsou nutné. Protože když píšete kód, píšete pro vaše současné potřeby, ale také pro budoucí lidi, kteří si musí váš kód přečíst, zjistit, jak to děláte, proč, a jak to provést.

Pokud to jen pamatujete, při programování/programování?

Jak to mohu snáze pochopit a upravit pro budoucí kodéry tohoto kódu, na kterém pracuji, pak uděláte dobrou práci. Pokud to neuděláte, bude to pro ostatní jen obtížné upravovat váš kód a nemyslete si, že to tak nikdy nebude, to je vzácné ...

Ve většině úkolů jsem musel vždy upravovat kód ostatních lidí a co nejvíce strašně psané, špatně zdokumentované.

Takže váš zvyk myslet na kódový dokument, který je sám, nedělá náležitou péči.

Jako programátoři musíme praktikovat sebekázeň, která se může zdát zcela a.r. nezkušeným programátorům, ale musí mít návyky, abychom se vyhnuli všem strašným zážitkům, které jsme měli s kódem jiných lidí. Nebo se dokonce podíváme na vlastní kód o několik měsíců později.

Podívejte se http://thedailywtf.com mají spoustu vtipných, ale skutečných příběhů o programátorech, kteří prostě nedělali svou hloubkovou kontrolu.

0
crosenblum

Na univerzitě nás učili téměř přeformulovat každý řádek kódu v angličtině s komentářem (pravděpodobně jen proto, abychom se dostali ke zvyku porozumět tomu, co kód skutečně dělá, spíše než jen něco kopírovat/vkládat a doufat v to nejlepší).

Osobně si myslím, že to z vašeho kódu zatěžuje peklo, takže je méně čitelné, než kdyby to byly jen komentáře nebo jen kód. Jsem C # kodér a jediné komentáře, které pořád uvádím, jsou bloky komentářů s "trojitým lomítkem", které jsou interpretovány zpět do dokumentace IntelliSense. Pokud se cítím obzvláště provinile za konkrétní způsob, jak něco udělat, nebo vypadá to zvlášť krypticky, dám další vysvětlení, ale to je o tom.

IMO: Self-documenting code je kód, kde názvy proměnných a metod jsou dány smysluplnými a kontextovými názvy, takže popisují, jaký je jejich účel.

0
James Love

Pokud jste svůj kód několikrát přepracovali a přesto jste nenašli způsob, jak objasnit záměr někomu, kdo zná doménu. Přepište funkci. Koneckonců to není více než 10-20 řádků. Pokud už je funkce delší, přepište ji tak dlouho, a proto je to nečitelné :) oplachování-opakování

a v nepravděpodobném případě je stále nejasné, co kód dělá, a vzpomněli jste si, že požádáte o pomoc své kolegy. Dobře, pak vám všem děkujeme za pomoc při vývoji Linuxu, protože to je kód jádra, který píšete, že? pokud ne opláchněte, opakujte shora :)

Jednoduše řečeno, nepište, že jste komentáře, KÓDY

0
Rune FS

Podívejte se na Code Complete 2. vydání, str. 128-129.

Abstraktní datové typy vás z tohoto hádanky zachrání. Self-documenting code je způsob, jak jít. Komentáře mohou být užitečné, ale mají

reálné subjekty spíše než implementace na nízké úrovni

můžete se vyhnout použití komentářů.

Jedna věc o komentářích je, že je napíšete jednou, ale nevidíte je, když implementujete funkci, vidíte je pouze při změně funkce.

Komentáře jsou opravdu užitečné, když jsou interpretovány IDE způsobem, jakým Delphi 2009+ nebo JavaDoc funguje, ale je to spíš strukturovaný značkovací jazyk, takže v jistém smyslu programujete svou dokumentaci, což je velmi chytrý.

0
Peter Turner

Věřím v mantru, že kód sám o sobě nedokumentuje, protože byste mohli být nejlepším programátorem na světě (Ada), a přesto nerozumíte tomu, co se děje, ale pokud dokážete proč a v krátkém rozsahu jak váš kód dělá to, co dělá, jak budete v budoucnu pomáhat sobě i ostatním.

0
Coyote21