Apró gondolat a kódban lévő dokumentációról és az IDE-kről

Kétféle dokumentáció létezik: a hasznos és a nyilvánvaló. Hasznos az, ami rendelkezik valami plusz mondanivalóval és olyan információt ad át, ami egy szignatúrából nem feltétlen derül ki. Például, hogy egy metódus, ami kikotor valahonnan valamit, az exceptiont dob-e vagy null-t ad vissza. (Most attól tekintsünk el, hogy szerintem referencia típusnál is csak akkor kellene engedélyezni a null-t, ha azt explicit megmondjuk, picit hasonlóan a Nullable<T>/foo?-hez.)

Ezen infók jellemzően fenn vannak az MSDN-en, vagy akár a metainfók között, csak épp a VS nem jeleníti meg, ami nem segíti túlzottan a produktivitást. Szomorú.

(Ha valaki unatkozik, szavazzon már erre: https://visualstudio.uservoice.com/forums/121579-visual-studio-2015/sug… )

Mellette viszont rengetegszer kinn van egy teljesen nyilvánvaló egysoros leírás. Ezeket sosem szoktam érteni, illetve azokat se nagyon, akik ezeket hiányolják. Vajon egy BizbaszManager osztály Bizbasz GetBiszbasz(string name) metódusa mégis mit művelhet? Mivel nyújt több információt az, hogy "visszaadja a name nevű Bizbasz-t", mint maga a metódus szignatúrája?

(Mondjuk tapasztalatom szerint azok szokták leginkább igényelni, akik képtelenek a kódot értelmezni.)

( persicsb | 2016. 07. 12., k – 08:26 )

A teljesen nyilvánvaló "returns FooBar" kommentek valószínűleg (mint ahogy maga a getter is) generáltak.

Nem vagyok ebben 100%-ig meggyőződve. Egyébként néha vannak fejlődések, pl. System.(Windows.Forms|Timers).Timer.Interval: [url=https://msdn.microsoft.com/en-us/library/system.timers.timer.interval(v… 4[/url]-ben még nem volt ott, hogy miben kéri, [url=https://msdn.microsoft.com/en-us/library/system.timers.timer.interval(v… 4.5[/url] óta ott van, hogy ezredmásodperceben.

De amúgy a fő kérdés igazából az, hogy a .NET FW esetén kinek hasznos, hanem úgy egyébként miért jó az, ha oda van írva Nyilvánvaló Kapitány stílusban a nyilvánvaló? Csak azért, hogy a PM-ek kipipálhassák a dokumentáció legyen?

----------------
Lvl86 Troll, "hobbifejlesztő" - Think Wishfully™

( BaT | 2016. 07. 12., k – 09:32 )

Ha egy kicsit belegondolsz, gyakorlatilag az egyetlen dolog, amit nem, vagy nehezen lehet kóddal kifejezni, az a mellékhatások, és az is csak nemtriviális esetben, mást felesleges dokumentálni.

Nem csak ezt. Runtime karakterisztikát sem várhatsz mondjuk egy sort() library függvény szignatúrájától, nevétől, pláne egy interfésztől.
Például van egy hashtable interfészed, N implementációval. Minden implementációnak a része az, hogy ez HOGYAN implementálja a megadott interfészt: mi a hash függvény.
Nem kell, hogy side effectes legyen a kód.