it-swarm-eu.dev

Není psaní poznámek uvnitř metod dobrým postupem?

Kamarád mi řekl, že psaní komentářů uvnitř metod není dobré. Řekl, že bychom měli mít komentáře pouze k definicím metod (javadocs), ale ne uvnitř těla metody. Zdá se, že v knize četl, že mít uvnitř kódu komentáře znamená, že v kódu je problém. Nerozumím jeho úvahám. Myslím, že psaní komentářů uvnitř těla metody je dobré a pomáhá ostatním vývojářům porozumět tomu lépe a rychleji. Uveďte prosím své komentáře.

63
Srini Kandula

Váš přítel se mýlí a jen velmi málo programátorů by s ním souhlasilo. Měli byste psát komentáře kdykoli a kdekoli máte pocit, že nejlépe pomáhají porozumět.

151
mqp

Ignorujte svého přítele. Komentář podle potřeby. Snažte se však, aby byl váš kód srozumitelný, takže komentáře nejso potřeba. Pamatujte, že váš počítač nevykonává komentáře, a proto je snadné se zbavit synchronizace s tím, co se ve skutečnosti děje.

Mám sklon používat blok komentářů, abych vysvětlil obzvláště složitou logiku, která by jinak potřebovala číst kroucení mozku. A pak se pokusím objasnit logiku a odstranit potřebu vysvětlení.

90
Michael Petrotta

Dobrý kód je dokumentující. Metoda by měla dělat přesně jednu věc a ta jedna věc by měla být zřejmá podle názvu metody a specifikace komentářů. Proto potřeba komentářů v metodě vysvětlující logiku naznačuje, že by metoda měla být rozdělena do metod s jedinou odpovědností.

Nyní, pro realitu. Tváří v tvář složité kódové základně špaget a snažíte se být správcem pěkný. Nemáte čas ani mandát na změnu 8 milionů řádků kódu, ai kdybyste to udělali, byly by nuance, protože všechno je složité. Co děláš?

44
Mark Peters

Překvapuje mě, kolik lidí s tímto názorem nesouhlasí.

  1. Dobrý kód by měl být samokumentující, takže byste měli pečlivě zvolit metody, názvy proměnných atd
  2. Vaše metoda by neměla být tak dlouhá, že na jedné obrazovce nevidíte celou metodu a komentáře

To znamená, že existují výjimky. Ale jsou to výjimky. A jde o výjimky, je to, že je jich málo. Skutečně stačí vysvětlit kód inline, pokud děláte něco kontraintuitivního.

Typická situace, kdy budete ve své metodě potřebovat komentáře, je, když použijete místní hack pro optimalizaci rychlosti, ale který při prvním čtení může dát jinému programátorovi moment wtf. To je dobrý bod pro přidání komentáře.

Ale obecně: ne, nepřidávejte do svých metod komentáře.

24
markijbema

Myslím, že mluví o takovém případě:

public void upload() {
    // destination Host
    String Host = ....
}

Kde byste mohli vylepšit kód tím, že budete mít explicitnější název proměnné než komentář:

public void upload() {
    String destinationHost = ....
}
18
Douglas

Věřím, že váš přítel odkazuje na „Čistý kód“ Roberta C. Martina. Myslím si však, že situaci příliš zjednodušuje. Kniha hovoří o tom, jak metodám dát jasná a popisná jména, což bychom měli všichni vědět, ale které nikdy nelze dostatečně opakovat. Kniha také doporučuje, aby byly metody velmi malé zabalením jakéhokoli bloku kódu, který může mít jasný a popisný název, do vlastní metody. Takže pokud máte pocit, že blok kódu potřebuje komentář vysvětlující, co dělá, pak byste měli udělat samostatnou metodu s odpovídajícím názvem. Teoreticky, pokud jsou všechny vaše metody pod 5 řádky a pokud mají všechny dobré popisné názvy, mělo by být zřejmé, co dělají, aniž by to musely vysvětlit v komentáři.

Neznamená to však, že byste nikdy neměli mít v rámci svých metod komentáře. Jde o to, že komentáře by neměly být nadbytečné. Měli by přidat informace. Pokud máte metodu, která dělá přesně jednu věc a ta věc je zřejmá z jejího názvu, nepotřebujete komentář vysvětlující, co dělá. Je však naprosto rozumné mít komentář vysvětlující, proč dělá svou věc tímto konkrétním způsobem. Možná budete chtít komentář vysvětlující, proč jste si vybrali jeden algoritmus před jiným, nebo proč jste si vybrali jednu datovou strukturu před druhou. Jinými slovy, chcete, aby samotný kód vysvětlil, jak to funguje, a chcete, aby komentáře vysvětlily důvody pro vaše rozhodnutí o návrhu, tzn. E. proč se věci dělají tímto konkrétním způsobem.

Kniha doporučuje namísto komentářů chybný kód refactoring. To je teoreticky skvělý nápad, ale ve skutečnosti možná nemáte čas ani infrastrukturu, například rámec pro testování pracovních jednotek s příslušnou sadou jednotkových testů. Jsou chvíle, kdy čelíte chaotickému kódu, který musíte včera pracovat, a jediným způsobem, jak se pohnout vpřed, je pokusit se porozumět chaotickým kouskům a komentovat je jako způsob, jak si sami dělat poznámky.

16
Dima

Ano, rozhodně píšete komentáře uvnitř metod v Javě.

Jak Konvence společnosti Sun říká:

Programy Java mohou mít dva druhy komentářů: implementační komentáře a komentáře k dokumentaci. Poznámky k implementaci jsou uvedeny v C++, které jsou ohraničeny /*...*/, a //. Komentáře k dokumentům (známé jako „komentáře k dokumentům“) jsou pouze pro Javu a jsou ohraničeny /**...*/. Komentáře dokumentu lze extrahovat do souborů HTML pomocí nástroje javadoc.

Takže komentáře v metodách jsou implementační komentáře.

8
zengr

Důrazně nesouhlasím s vaším přítelem a tvrdím, že inline funkce komentáře jsou velmi důležitou součástí psaní dobrého kódu. Funkce komentáře jsou navrženy tak, aby klientům kódu lépe porozuměli tomu, co má kód dělat - co znamenají jeho parametry a návratové hodnoty, druhy invariantů, které očekává při vstupu a výstupu atd. Inline komentáře však jsou zaměřeny především na udržovatele kódu a ideálně jako série mentálních poznámek pro původního autora kódu. Umožňují nahlédnout do složité metody, kterou přečetla jiná osoba, a intuitivizovat, co si myslel původní autor. Rovněž usnadňují diagnostiku chyb, protože pokud komentáře popisují, co je záměrem kódu a jaké předpoklady vytváří, může být mnohem snazší zjistit, jak je část kódu chybná, když je zjištěna závada.

Osobně považuji vložené komentáře za užitečné, protože mě nutí, abych si dokázal, že kód, který se chystám napsat, bude fungovat správně. Často si zvyknu, že nebudu psát žádný kód, aniž bych nejprve jasně komentoval, co má v úmyslu a jak to bude fungovat. Vícekrát než ne, to mi brání dělat hloupé chyby v kódu, protože zjistím, že moje vysvětlení je nesprávné nebo nebere v úvahu případ Edge.

Každý má samozřejmě svou vlastní disciplínu kódování a pro některé lidi je snadnější psát kód bez vložených komentářů a místo toho ho rozdělit na několik menších metod. Ze zkušenosti jsem však zjistil, že vložené komentáře jsou neocenitelné během vývoje a ladění a jsou nesmírně užitečné pro ostatní lidi, kteří se musí podívat a udržovat svůj kód dlouho poté, co jsem se přesunul do jiného projektu.

6
templatetypedef

Váš přítel může dobře vyjadřovat názor, že komentáře jsou, pokud ne, „vůní kódu“, „ deodorant “. To není specifické pro komentáře v metodách, ale může to být spíše pravdivé pro komentáře v metodách než pro komentáře v preambuli.

Když píšete komentář, obvykle je to něco vysvětlit. Když něco potřebuje vysvětlit - no, není to samo-vysvětlující. Velký kód je samovysvětlující. Když tedy přidáváte komentáře, zakrýváte jeho neúspěch v sebepřesnění, aniž byste to vysvětlili. Takže pokaždé, když napíšete takový komentář, namísto změny kódu - přejmenováním, extrakcí metod atd. - na učinit samo-vysvětlujícím, nedosahuješ ideálu.

Ale my občas nedosahujeme dokonalosti. A často je lepší přidat vysvětlující komentář, než nechat těžko pochopitelný kód nezdokumentovaný.

6
Carl Manaster

Dobré komentáře vysvětlují, proč ne jak. To je klíčový rozdíl zde. Většina lidí bude moci sledovat, co děláte, ale proč jste to udělali, vyžaduje další komentáře. Tyto připomínky by měly být co nejblíže operaci.

3
Bill Leeper

Při komentování kódu (nebo skutečně špatně zdokumentovaného kódu někoho jiného) můžete často čelit pocitům čirého znechucení , nenávisti ) nebo hněv . Kód se může chovat frustrujícím a nečekaným způsobem a možná budete muset přidat nějaké velmi zlé hacky, aby to fungovalo po určitou dobu.

Ve všech případech vyjádření vašich pocitů anotací příslušných částí kódu některými těžkými přísahami (viz linux kuxel fuckcount ) je běžná praxe. Tyto komentáře musí žít uvnitř metod tak, aby se neobjevovaly v automaticky zdokumentovaném API, takže ani váš šéf, vaši klienti ani jiná agnostická osoba se zdrojovým kódem ji nikdy neuvidí.

Vaši spolupracovníci se však při studiu zdroje budou cítit skvěle a štěstí . (A samozřejmě si můžete přidat poznámky nebo použít zdrojový kód jako komunikační médium do určité míry, #TODO: add more examples here)

Samozřejmě byste mohli tvrdit, že tyto druhy komentářů by neměly být na prvním místě, nebo že by měly být odstraněny před konečným vydáním, ale v dnešní době mají softwarové projekty velmi krátké cykly vydání a některé komentáře jsou stále relevantní mnoho nočních sestavení později, takže možná by se váš přítel měl začít učit číst (a psát) mezi řádky .

2
codecraft

Je hezké mít kód, který nevyžaduje komentování. Když dostáváte, ukládáte a odstraňujete věci, máme docela dobrý nápad, co se děje a nepotřebujeme komentáře.

Někdy je kód chaotický a je kandidátem na refaktoring, takže možná budete muset mezitím komentovat.

Dnes jsem měl řadu kódu nedělejte, co se očekává. Datatable .net zřejmě nemyslí, že importovaný řádek je nový záznam. Když vložíte záznamy z tabulky, nic se nestane. Importovaný řádek musí nejprve změnit svůj stav. Jednoduchý komentář je vše, co je potřeba, takže když se k němu vrátím za 6 měsíců a pomyslím si: „K čemu to sakra potřebuji?“ Budu vědět.

1
JeffO

Programátoři běžně vkládají komentáře do metod, kdykoli si myslí, že není pro ostatní programátory jasné, co kód dělá. Programátoři také někdy vkládají do metody komentáře TODO. Je však pravda, že pokud máte uvnitř metod příliš mnoho komentářů, možná budete muset ustoupit a přemýšlet, pokud děláte věci příliš komplikované, než by měly být. V jiném Wordu se pravděpodobně budete chtít vyhnout komentování něčeho zjevného pro ostatní programátory, protože je těžší přečíst si s nimi kód.

Chcete-li návrh svých přátel přijmout pozitivně, měli byste si pamatovat, že se můžeme vyhnout příliš velkému komentování řádným pojmenováním proměnných a metod a udržet každou metodu malou a zajistit, aby příliš mnoho personálu nedělalo.

1
knoguchi

Myslím, že důvod, proč řekl, je ten, že věří, že funkce by měly být dostatečně krátké, aby každá z nich obsahovala pouze jednu koncepční operaci.

Nemusím nutně souhlasit s touto vírou v její extrém (z různých důvodů, včetně toho, že čtení takového kódu se může stát noční můrou), ale pokud ano, mohlo by to znamenat, že by měli pouze jednu poznámku na funkci, protože existuje pouze jeden koncept na funkci a jeden komentář na koncept.

Ať tak či onak, používám komentáře kdykoli a kdekoli, kde je kód, jehož výběr nebo chování nejsou okamžitě zřejmé - často se týkají výkonu a esoterické matematiky. Takové věci se často bezprostředně netýkají spotřebitele funkce, takže bych tvrdil, že je vlastně dobrý nápad to skrýt před dokumentací.

1
Rei Miyasaka

Věřím, že váš přítel mluvil o javadocu, který vygeneruje dokumentaci z vašeho komentáře, pokud je nad deklarací metody (a je zdobena hvězdičkou), jako je tento:

/**
   get a webpage for a given url 
   @param url: the url to get
   @returns String: the http-source 
*/
public String getWebpage (String url) {
... 

Pokud vložíte tento komentář do metody, je to zbytečné.

Proto - zpravidla: vkládejte komentáře do zdroje Java zdroj nad metodu).

Výjimky mohou a budou nastat. Souhlasím s: používat krátké metody, psát samokumentující kód. Javadoc jako nástroj však podporuje duplicitu komentářů, protože jinak vypadá v dokumentaci tak nahý. :)

1
user unknown

Připouštím, že v metodě psané od nuly by člověk dokázal zdokumentovat svou funkci pouze v záhlaví. Nicméně.

Zjistil jsem, že komentáře jsou často vkládány tam, kde byly objeveny chyby a jemná nuance byla přehlížena i když metoda má pouze jednu odpovědnost - což je upřímné, je zřídka případ v původním kódu. Dále nevidím důvod, proč by měl název proměnné dlouhý čtyřicet znaků (i když se používá pouze na dvou místech), když lze kratší název proměnné s stručným komentářem snadněji strávit a znovu použít. Čisté a stručné je nejlepší, ale především je to prostředek komunikace s jinými programátory, stejně jako e-maily, dopisy a poezie. A k tomu přidám nabídku:

"Tento dopis jsem prodloužil pouze proto, že jsem neměl čas ho zkrátit."

Blaise Pascal, (1623-1662) Lettres provinciales

1
M. Tibbits

Díky komentářům je kód přátelštější pro programátory, nezapomeňte, že komentáře nebudou provedeny.

Pokud byste si měli přečíst svůj kód po několika měsících, komentář vám usnadní čtení kódu.

Usnadní udržování kódu a každému jinému programátorovi, který se na něj podívá, bude snadné pochopit logiku, kterou jste implementovali.

To neznamená, že musíte vždy přidávat komentáře i pro metodu s několika řádky kódu.

Stejně jako například následující kód je samovysvětlující a nevyžaduje žádné komentáře k objasnění jeho funkce

public String getName(){
    return name;
}

Když je metoda velká, přidejte komentář, takže je čitelnější pokaždé, když se na ni jakýkoli programátor podívá.

Pamatujte si, že při kódování si můžete myslet, že kód je samovysvětlující, ale když se na něj podíváte po šesti měsících, komentáře, které jste přidali před šesti měsíci, vám určitě pomohou, nebo jakémukoli jinému programátorovi kód rychle pochopit.

0
Alpine

Problém s vloženými komentáři je v tom, že je třeba je udržovat spolu s kódem (platí to i pro komentáře na úrovni funkcí/metod/modulů/tříd, ale ne až tak velké míry); Bůh ví, kolik zdrojového kódu je stále tam, kde komentáře nemají absolutně nic společného s kódem, který již dokumentují, což IMO je stejně špatné nebo horší než vůbec žádné komentáře.

V ideálním případě by měla být inline dokumentace omezena na následující situace:

  • Vysvětlení kódu, který je silně optimalizovaný nebo „komplikovaný“, spolu s odůvodněním pro proč kód je tak silně optimalizovaný nebo „komplikovaný“ („chyběli jsme požadavku na výkon X a profilování ukázalo, že v tomto je úzký profil) sekce; optimalizace níže získala výkon Y% ");

  • S odkazem na normu nebo požadavek ("odstup DTED 0 po 30 sekundách");

  • Identifikujte kód, který vyžaduje další analýzu/vývoj („TODO“);

První zákon dokumentace kódu - nedokumentujte to zřejmé. V souladu s prvním zákonem o dokumentaci kódu - napište kód, který je v co největší míře zřejmý.

0
John Bode

Nejprve byla vaše otázka konkrétně zaměřena na Javu - což významně ovlivňuje odpověď.

Množství komentářů, které je povinné, velmi souvisí s jazykem, ve kterém pracujete.

  • Některé jazyky, například Java a C #, se velmi dobře hodí k konceptu samokumentujícího kódu. V těchto jazycích je vaše úsilí nejlépe vynaloženo, aby se samotný kód stal co nejčitelnějším a popisným a pak přidejte in-line komentáře pouze k věcem, které v jazyce nelze nativně popsat.

  • Některé jazyky, například SQL, jsou obtížnější, aby byly dobře čitelné. Syntaxe, pořadí hodnocení, vnoření atd. Může být náročnější navrhnout samokumentaci. Stejný základní přístup stále platí: zaměřte se na používání jazyka v co největší míře, poté přidejte komentáře, abyste nahradili oblasti, které jsou nejasné nebo matoucí.

Celkově nemůžete 100% zrušit komentáře, ale vaším cílem by mělo být odstranit need pro komentáře co nejvíce tím, že kód bude více popisující. Výsledkem těchto snah je obvykle méně kódu a lépe organizovaný kód. Bez ohledu na to, zda jsou stále k dispozici komentáře, to znamená, že váš kód bude mnohem lépe udržovatelný a přístupnější - což je opravdu to, s čím se v jakémkoli ohledu zamýšlí.

0
STW

Myšlenka, že Javadoc (nebo dokonce Delphi autocomplete rady) by měla změnit způsob, jakým osoba kódy (kromě přidávání funkcí pro javadoc), je docela absurdní.

Zeptejte se přítele, který přišel jako první, javac nebo javadoc?

Je to jako ptát se, kdo přišel jako první, kráva nebo paní O'Leary


Javadoc by také měl být pro lidi implementující vaši třídu a funkce, komentáře v kódu jsou pro lidi, kteří váš kód udržují. Zejména u vašich soukromých metod by se nikdo nemusel nutně dívat na váš kód, aby viděl, co dělá. To je to, k čemu jsou dokumenty. Ale pokud někdo potřebuje Tweak něco kvůli chlupatému off o jednu chybu, pak to chcete komentovat ve své metodě.

Je zřejmé, že předpokládá, že 90% kódu, který je ve skutečnosti opravou chyb, je špatných. Nikdy jsem nečetl „pragmatického programátora“, ale mohu předpokládat, že na tu knihu neodkazuje.

0
Peter Turner

Teď, když je párty docela dobře, hodím své dva centy. Používám komentáře, když popisuji konkrétní kousek obchodní logiky, nebo když musím přidat něco, abych zakryl nepředvídaný případ Edge.

Kód se postupem času vyvíjí, aby zohledňoval věci, které předtím nebyly známy, a tak když použijete band-aid, namísto předpokladu, že je známo proč dáte tuto band-aid na, někdy to pomůže přidat malý blok v kódu, který říká: "Mimochodem, musel jsem to opravit a tady je odkaz na bugtracker, takže můžete sledovat okolní konverzaci" a v mém případě (když používám FogBugz) by to vypadalo takto :

//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );

nebo cokoli. Mám tedy na mysli, že něco, co se zdá být na místě a není tak čitelné, je pravděpodobně dobré místo pro vložení dokumentu. Shromážděné znalosti jsou krásná věc.

Ale můj první bod byl moje obchodní logika. Doslova mám v uložené proceduře blok, který se chystám přepsat tento AM, který má v popředí některá obchodní pravidla.

/****************************************************************
author  yourstruly
date    2010-11-18
descrip intended use is to blah blah blah
        ended up over actual measured blah blah blah according to blah blah blah
        rules from the customer are:
        If the sum of the blah blah blah is higher than the blah blah blah
        and the blah blah blah contain blah blah blah,
        and the blah blah blah is non-zero,
        recalculate the blah blah blah to fit within the blah blah blah

        Additional rules for us internally: 
        if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)

        rewritten here with (1) traceable statements for the where clauses.
        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is non-zero (9)
        and the blah blah blah is lower than the blah blah blah (4)
        and the edited blah blah blah is higher than the blah blah blah (5)
        then recalculate the blah blah blah (6)
        // See note lower in this document on the math

        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is higher than the blah blah blah (7)
        then set the blah blah blah to zero (8)

        (7) dictates the same as (4) but it's easier to do (7)
****************************************************************/

Sorry for the blah blah blah's but proprietary rules and all that ;)

A najednou vidíte, že mám požadavky (!) Vložené do mého kódu jako komentáře a mohu je označit jako komentáře jako /*(1)*/ (což dělám), aby to bylo snadno dohledatelné pro dalšího zaměstnance (což bylo, a on byl schopen najít části, které potřebovaly vyladění okamžitě) a pak, pokud někdo chce vědět, co je specifikace, může číst komentář shora, a pokud někdo chce vědět, co je to pseudokód, je to tam a pokud někdo chce převést pseudokód na tento kód, pak jdete. Pro mě je to mnohem čitelnější (pro můj případ), protože zachovává původní požadavek (odříznutý z e-mailu) a umožňuje rychlou shromáždění sledu myšlenek bez přílišného přemýšlení a umožňuje použití snadných transformací pseudo do skutečného kódu.

A ano, existuje několik inline komentářů, které říkají, že takové a takové nefungovaly tak, jak se očekávalo v pseudokódu, protože požadavek se úplně neshodoval s údaji, takže jsme potřebovali data vyladit. Ale to je můj názor. Zdokumentovali jsme in-line případy Edge a nechali jsme pseudokód v kódu, aby se řídil logikou, takže jsme všichni věděli, co se od původních požadavků očekává

0
jcolebrand