Vlákno názorů k článku
Java zavádza markdown syntax do komentárov
od Don J. - Tak ono se to v C# hlavně nepoužívá...
-
Tak ono se to v C# hlavně nepoužívá jako komentář, jak si autor představuje, ale jako tool/tip nad tou danou funkcí/procedurou, kterou chce použít.
Jakmile někde chci použít funkci Reviews z příkladu, vyskočí mi tooltip s popisem a celé to info je hezky formátované a přehledné.
XML je ve Visual studiu generované, stačí napsat tři lomítka (///) a IDE připraví komplet celé XML, které se jen vyplní. Navíc se dají např. použít i odkazy na třídy a nebo dokumentaci pomocí, pomocí tagů see, seealso, atd.
Komentáře se píší za 2 lomítka či do bloku /* */Hlavně bych být autorem nic neočekával, žádná změna se konat nebude, protože není potřeba nic měnit :), přínos by byl totiž roven nule.
-
Tak ono se to v C# hlavně nepoužívá jako komentář, jak si autor představuje, ale jako tool/tip...
Ak sa Vám nepáči slovo (dokumentačný) komentár, tak si berte dokumentačný reťazec. JavaDoc je ekvivalent documentation string v C#.
JavaDocs/documentation strings sa rozhodne nečítajú výlučne v HTML outpute/tooltipoch, ale často priamo v kóde. Pozriem si napr. zdrojový kód nejakého projektu priamo na Githube, trebárs https://github.com/dotpcap/sharppcap/blob/master/SharpPcap/ARP.cs
Z dokumentačného reťazca sa dozviem, že PhysicalAddress
Resolves the MAC address of the specified IP address. The 'DeviceName' propery must be set prior to using this method.
XML je ve Visual studiu generované, stačí napsat tři lomítka (///) a IDE připraví komplet celé XML...
Takto to funguje aj v Jave od nepamäti. Tu nejde o jednoduchosť generovania doc stringov, ale o celkovú ergonómiu výsledného kódu, ktorého súčaťou sú aj komentáre/dokumentačné komentáre.
-
Tak zrovna když se podívám na tebou odkazovaný kód, tak:
1) Není vůbec jasné o jaké DeviceName je řeč, není to property ani funkce v této třídě. - viz část dokumentace, kterou jsi zkopíroval2) O PhysicalAddress se nedozvíš vůbec nic, dozvíš se o tom, co dělá funkce Resolve, tedy pokud to beru podle toho co jsi zkopíroval.
To summary je na začátku pro to, aby jsi zjistil, co daná funkce dělá. Parametry tě v tu chvíli nezajímají, hlavně by vždy měl název funkce vypovídat o tom, co dělá, což v tomto případě je v pořádku. Následně jsou v kódu komentáře, abys věděl jak to ta funkce dělá, resp. co používá a proč.
-
KateStříbrný podporovatel
To fakt vypadá jako buď dokumentace co oddriftovala od reality, nebo chybějící link v dokumentaci. To první řeší celkem hezky Rust přes doctesty. Příklad použití přímo v dokumentaci a pokud se změní api bez změny dokumentace, failne doctest.
-
Ta egonomia je prave dost dobra. Clovek to oceni, ked do dokumentacneho komnetaru potrebuje vrazit nieco viac ako dve slova. Kludne viac riadkov, alebo ukazku kodu, zoznamy, formatovanie a neviem este co vsetko (to C# dokaze od roku pana 2005).
Z moje skusnosti, ak ma byt dokumentacny komentar kratky, tak ho zvycajne nema cenu pisat, lebo clovek zisti vstekoz typov pouzitych v metode.
-
Ten dojem, že code review jsou všemocné mě nikdy nepřestane fascinovat. Reálně kde jsem kdy pracoval, tam to všechny skoro vždy naprosto otravovalo od autorů až po revidující o tom, že to navíc dost výrazně zhoršovalo mezilidské vztahy a tedy i fungování týmů ani nemluvě. Podle čehož ten proces fungoval jako celek. Teorie je hezká, ale praxe je obvykle úplně někde jinde.
-
@martinpoljak
Raz dali bez môjho vedomia robiť code review juniorovi, lebo ho chceli utilizovať. A ten nevedel, ako funguje Spring. Len došiel so smutnými očami "prepáč, pokazil som to" (použil expresívnejší výraz), Jenkins mi napísal, že tie metódy mám odstrániť. Ale taký bol smutný, že som sa ani hnevať nemohol :)
-
L.Stříbrný podporovatel
Code reviews nejsou samospásné řešení ale nástroj který se, jako ostatní nástroje, může používat dobře a muže se používat špatně. Když se používá dobře, pomáhá zvyšovat kvalitu kódu, například tak, že omezí podobné nesmyslné komentáře. Pokud se používá špatně, výsledkem je otrava a zkažené mezilidské vztahy, jak píšete.
-
Tak jestli se u vás kazí vztahy kvůli code review, tak by se vám dřív nebo později ty vztahy pokazili I bez code review. Podle mě ten váš tým moc dobře nefunguje. Otrava to je když se nedodržují pravidla. Tj. MR musí být malé a dodržovat daná pravidla. Raději si ušetřím čas a odhalím problem v code review, než když to na mě vybafne později. Je to pojistka proti vývojářům, co se si to snaží ulehčit a ojebat. Už jenom to, že člověk píše kód s tím, že ho uvidí někdo jiný ho nutí psát pořádně, napsat testy (vždy mě fascinuje, že existují v dnešní době stále lidí co testy nepíšou). Code review od juniora nemusí být vůbec špatné. 1. Ho to posouvá, minimálně ve skillu čtení kódu někoho cizího a 2. Někdy mají junioři jiný pohled, které seniora nenápadně, protože to již dlouho dělá takhle.
