Názory k článku
Java zavádza markdown syntax do komentárov

Moc tú dokumentáciu nepoužívam, resp. nevytváram, neviem či sa naozaj píše ručne ako xml, ale podľa mňa sa nečíta priamo, ale cez tooltipy, kde je naformátovaná

Generuje ju nástroj javadoc, prípadne sa dá použiť doxygen.

Nevim jak v C#, ale v C/C++ se casto divam primo do kodu a neni spatne i primo ty komentare mit rozumne citelne, pomaha to rychlejsi orientaci. To XML je absolutne necitelne.

Od toho jsou IDE která ty komentáře ukazují rovnou rozumně čitelné.

IDE driven development? S tímhle přístupem hodně štěstí.

To nesouvisí.

Můžeš použít kopec výhod IDE a přitom nejít do IDE driven.

Tohle je super, ale zrovna javadoc mě moc netrápí a mám strach, že ta dokumentace bude pak roztříštěná jako např. v Python. Mnohem větší přínos pro mě měl JEP 413: Code Snippets in Java API Documentation

Prosím, co přesně na tom vidíte jako "super"?

Markdown je otřesný bastl, proto zde taky používají CommonMark, který se to snaží nějak usměrnit. Ano, někde je asi taková možnost soudobější (což neznamená nutně lepší) než psát Javadoc/HTML, ale zrovna tohle rozhodnutí mi přijde jako zcela zbytečné zesložitění implementace, která už tak není nikterak jednoduchá. Navíc to vyžaduje knihovnu commonmark-java, tedy další závislost...

Ani vlastně nevím, proč by to vůbec měl jazyk explicitně podporovat, když se jedná o komentáře, které by v příčetném prostředí měly být vyjmuty z interpretace. Maximálně by se na tento stupeň analýzy kódu mělo být možné připojit a udělat si tam nějaké další zpracování - přesně aby se nemusely dělat takové nesmysly.
Samozřejmě jazyk taky mohl mít od začátku systém na podporu metadat. Do toho se daly schovat jak typy, tak další informace, které by se daly automatizovaně zpracovat během překladu, při testování, nebo případně za běhu.

Markdown je ale lidsky čitelný - já si občas píšu v MD poznámky a čtu je v plaintextu.

HTML, XML nebo json jsou taky lidsky čitelné

A jsou lidí, pro které je čitelný i strojový kód

Sorry ale psát listy a tabulky v javadoc s html je prostě opruz a čitelnost v raw formátu to je dost na nic, což mě u formátu dokumentace přijde jako problém, protože to pak musím číst během code review. Navíc MD používám skoro všude, Wiki, Stackoverflow, Github, Gitlab atp. takže to je pro mě naprosto přirozená forma psaní. Tohle o html prostě říct nemůžu protože je to hrozný opruz psát ručně elementy. Jak už jsem psal největší pain s javadoc vyřešili se @snippet, do teď mi není jasné jak někdo může udělat dokumentační formát v kterém se špatně píše kód jazyka pro který je určen (ano anotace byly přidány dodatečně ale i tak).

Že to zesložiťuje implementaci, která je už tak složitá a zrovna MD se stejně skoro všude používá. A věřím, že zrovna architekti Java dobře vědí, co je ok a co není. A tady jasně převažuje čitelnost takové dokumentace nad nevýhodami zpracování.

Jenom pro srovnání:

/// Something `something`
///
/// This is *important*
/// # List
/// * item1
/// * item2
///
/// # Table
/// | Latin | Greek |
/// |-------|-------|
/// | a     | alpha |
/// | b     | beta  |
/// | c     | gamma |
///

vs

/**
 * Something `something`
 * <p>
 * This is <b>important</b>
 *
 * <h1> List</h1>
 * <ul>
 *   <li>item1</li>
 *   <li>item2</li>
 * </ul>
 *
 * <h1>Table</h1>
 * <table>
 *     <tr>
 *       <th>Lating</th>
 *       <th>Greek</th>
 *     </tr>
 *     <tr>
 *       <td>a</td>
 *       <td>alpha</td>
 *     </tr>
 *     <tr>
 *       <td>b</td>
 *       <td>beta</td>
 *     </tr>
 *     <tr>
 *       <td>c</td>
 *       <td>gamma</td>
 *     </tr>
 * </table>
 */

Mimochodem co ja bych dal za to i kdyby tady na root šlo psát MD.

6. 5. 2024, 08:57 editováno autorem komentáře

Prostě tooling je na nic, tak narveme všechno a kitchen sink přímo do jazyka/ platformy. To neumí jednoduchý nadpis, seznam a tabulku vyrenderovat IDE způsobem WYSIWYG přímo v komentáři? Mohl bych tam mít i pěkně udělané proporční písmo. Diff mimochodem může být také vyrenderovaný, když v komentáři rozpozná blok, který by bylo vhodné interpretovat/ renderovat.

Proč by to mělo renderovat IDE a všechno co to zobrazuje (code review, git, diff), když je tu řešení, které poskytuje pěknou čitelnost? Se změnou formátu se nic nemění stále to budete moci vidět naformátované v IDE. Navíc to vůbec neřeší, že zápis HTML v Javadoc je dost opruz a spoustu lidí to odradí aby dělali ty komentáře pěkné a formátované.
Další jazyky jako Rust, Kotlin, Go atd. mají dokumentační komentáře také postavené na MD, tak proč zrovna v Javadoc by to nemohl umět taky? Takže by se dalo říct, že MD syntax se stává standardem ve formátování dokumentačních komentářů.

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/docu­mentation 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/doku­mentač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íroval

2) 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č.

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.

Psaní komentářů vyžaduje skill. Miluji komentáře ve stylu:
/**
* Spočítá hodnotu.
* @param int id
* @return String
*/
String calculateValue(int id) {}

3. 5. 2024, 17:03 editováno autorem komentáře

Ak je kód dobre napísaný, tak je samodokumentujúci sa. Vraj taký niekde videli.

Mne ani nevadia odfláknuté komentáre, ale nepravdivé komentáre, keď sa niečo upraví a komentár zostane pôvodný, grrr .......

Tohle by ovšem nemělo projít přes code review.

diky. Nejak sem to minul. A tne jep je poctivej, skoro ucebnice markdownu pro javisty :)

Ono to barvičkách vypadá o dost líp a ty tagy to generuje při psaní samo intelisense, tak to je celkem dobré. Navíc se to používá jen u knihovního kódu public members...
Ale to MD taky nemusí být špatné.

> Je to neprehľadné a nezmyselne zahustené XML značkami. Ide o jednu z mála vecí, ktorú C# podľa môjho názoru horšie implementoval.

A nebolo to práve cieľom? Však v Jave a C# (a v iných "OOP" zameraných jazykov) ide o to mať čo najviac boilerplatu a obskurdnej syntaxe. Zrejme aby programátory čo sú platený od počtu znakov/riadkov, aby mali viac $$$. Inak vidím že JavaDoc sa silne inšpirovalo s JSDoc (JavaScript)

5. 5. 2024, 18:05 editováno autorem komentáře