Programozási leírások közül az alábbi felépítésűt kedvelem:

Mit kell választani, ha működés leírását szeretném, és minde egyes funkció után egy példát?

És mi a különbség a kódrészlet és a példa között?

a "Nincs szükségem a leírásokra" és a "zseni vagyok" 2 külön kategória szerintem, de biztos ami biztos, bejelöltem azt, ha már ilyen kedvesen felajánlottad. a pozitív hozzáállás mindennél fontosabb :)

Több félét is jól használhatónak tartok!
Legyen teljes működő, kipróbálható kód. És hogy hol van a magyarázat, az elv ismertetése az nem annyira fontos, csak legyen!
--
Tertilla; Tisztelem a botladozó embert és nem rokonszenvezem a tökéletessel! Hagyd már abba!; DropBox

A lenyeg, hogy a dokumentacio es a kod ne mondjon ellent egymasnak -- ahogy az elo szokott fordulni regota fejlodgeto rendszereknel.

----------------------
while (!sleep) sheep++;

Mindegy, csak ne doxygen alapú legyen. Az olyanok tipikusan azt az információt tartalmazzák, amit amúgy is tudsz... :-/

A felepites maga a legkevesbe sem erdekel, tobbfelekeppen lehet jo leirast csinalni. Sot, sok esetben maga a tartalom, vagy a megcelzott kozonseg donti el, hogy melyik felepites celravezetobb.

Lattam mar zsenialis, tisztan elmeleti leirast forraskod es pelda nelkul, amit fel tudtam hasznalni kesobb, es olvasni is elvezet volt. De lattam olyan forraskodot is, ami pusztan kod volt, komment es magyarazat nelkul, de annyira szep volt, hogy onmagaert beszelt, es az, hogy nem volt hozza szukseg magyarazatra, csak megszebbe tette.

Egyebkent meg zseni vagyok, es nincs szuksegem leirasokra. Igenyem azonban van ra, mert mint minden magara valamit is ado zseni, lusta is vagyok. :P

--
|8]

Ez attól függ miről van szó. Ha mondjuk szeretnék használni egy libet akkor pár bevezető kliens oldali kód + forráskód + kommentek a nem triviális részeknél + nyelvfüggő dokumentáció normálisan (pl. javadoc). Sok példa van erre szerencsére.

--
http://neurogadget.com/

A komplett működő példákat nagyon szeretem. Plusz fordítási, használati leírás. Ha önmagában működésre tudok bírni egy libet a példaprogrammal 5 percen belül, akkor már boldog vagyok. A legtöbb esetben ez nem szokott működni.

Sokszor az a probléma, hogy a példák valami olyan függőséget is használnak, amiket nem triviális beszerezni, pedig nem kellene feltétlenül a példába.

Az eredményből látszik, amit amúgy is sejthetett mindenki, hogy az emberek általában a lépésről-lépésre leírásokat szeretik és a végén összegezni.

"Nincs szükségem leírásokra, zseni vagyok"
De szoktuk szeretni, amikor ilyen "zsenik" adnak át nekünk maintenance-re kódokat. :)
--
"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." John F. Woods

Get dropbox account now!

Sajnos a SOK programozó ezeket a lehetőségeket nemigen ismeri, kivéve az utolsót ... elnézést a kivételektől, mert láttam már értelmezhető működést és kódot, csak már nem emlékszem rá, hogy mikor :S

Nem vagyok zseni ezért én a Qt dokumentációját tartom iránymutatónak. Bárcsak mindegyik nyelvhez hasonló hatékonyságú dokumentáció lenne. Van részletes leírás és némelyik objectumnál szinte mindegyik funkcióhoz van kódrészlet is . De ha valakinek ez sem elég akkor ott a rengeteg példaprogram.

2 3 6 mind jó

--
CyclonePHP

Nekem az MSDN és a Qt dokumentációja jön be.
--
http://naszta.hu

Érdekes, hogy a könyv nem szerepel és nem hiányzik senkinek - pedig a legmélyebb ismereteket egy komplett átfogó (és normálisan, nem magyar minőségben megírt) könyvből lehet összeszedni. Az ilyen a neten utánabúvárkodok dolgokból rendszerint csak az szokott lejönni, hogy valamiért megint nem működik és akkor jön a toldozgatás foldozgatás.

Kimaradt: "Nincs szükségem leírásokra, úgysem tudok olvasni"
--
Ingyenes Ubuntu One tárhely:
https://one.ubuntu.com/referrals/referee/170278/

Sajna én nem hinném hogy megtaláltam volna ami nekem kell, de kérlek javítsatok ha tévedek. Én azt szeretem, ha leírják a működést, amit képekkel és példa műveletekkel szemléltetnek, és a fontosabb helyek, és szekciók kommentekkel jelölve vannak a kódban.