- A hozzászóláshoz be kell jelentkezni
Hozzászólások
Kulon dokumentacio --> megrendelonek/management reszere
programbol elerheto --> user szamara
forraskodan levo --> fejlesztoknek
Ez 3 teljesen kulonbozo dokumentacio kapasbol, minimalis atfedessel.
--
"You can hide a semi truck in 300 lines of code"
- A hozzászóláshoz be kell jelentkezni
+1
BlackY
--
"en is amikor bejovok dolgozni, nem egy pc-t [..] kapcsolok be, hanem a mainframe-et..." (sj)
- A hozzászóláshoz be kell jelentkezni
pontosan, ezeket osszemosni szarvashiba.
- A hozzászóláshoz be kell jelentkezni
+1
Még annyival egészíteném ki, hogy a forráskód szintjén levő megjegyzések mellé érdemes egy globális, a felépítésről, gondolkodásmódról levő doksit is készíteni, sokat segít, ha nem a kódon belül kell találgatni, hogy most épp melyik modult és mi és honnan és mi alapján tölti be (persze ha úgyis teljes átvétel van, akkor ez se elkerülhető, én csak kisebb hibakeresésre, bővítésre gondolok, hogy hasznos a "térkép"). Viszont ezt gondolom sokan azért se írják meg, mert a javítást-bővítést majd ők végzik, ha meg már nem, akkor ugyan nem érdekli őket a következő programozó lelki üdve.
- A hozzászóláshoz be kell jelentkezni
A kód öndokumentáló. A "mire gondolt a költő" típusú fejlesztőknek szóló dokumentáció a class mellett lehet markdown formátumban, együtt push-olva a repoba. ;)
Az ilyen handleFailEvent() /* This event handles failures */ típusú kommenteknek én nem sok értelmét látom.
--
"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
- A hozzászóláshoz be kell jelentkezni
Arra gondoltam, hogy nem ártana egy madártávlati kép némelyik programról, nem class szinten, hanem milyen tech-et miért választottunk, milyen pattern-eket miért választottunk, és nagyjából mit merre keress. Minden másra jó a kódba írás, és szerintem is elég a "weird" részek megmagyarázására, de ha nem egy elterjedt felépítésről van szó, sokat segít, ha tudom hol keressem azt a mit.
- A hozzászóláshoz be kell jelentkezni
Szia,
+1, aki másképp állítja, az nem dolgozott nagyobb léptékű (több száz ezer kód soros ) programon.
A nagyobb projekteken (nem pénzben, hanem digitális kiterjedésben) a kód öndokumentáló jellege már messze nem elég :)
Üdv,
LuiseX
- A hozzászóláshoz be kell jelentkezni
Millió soros kódon dolgozom. Értelmes class/függvény szervezés, beszédes függvény/változó nevezéktan, és minden elég jól érthető, nincs szükség kommentezésre. Amit a /**/ kommentben le tudnál írni, az egy icipici gondolkodással simán visszafejthető.
--
"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
- A hozzászóláshoz be kell jelentkezni
Szia,
Amit az előző kommentben leírtál, "madártávlati leírás" az, amire én is gondolok.
Többször volt szerencsém átvenni olyan terméket, ami több belépési ponttal, vagy vezérlés forrással rendelkezik , és tapasztalatból mondom, hogy egy gyors áttekintő mindegyiknél sokat segített volna.
Nem step-by-step, hogy is működik a kód leírásra gondolok, csak arra, hogy miképp kommunikálnak a modulok ( és modulok alatt nem 2 .cpp-re, hanem kimeneti binárisokra, illetve futtató komponensekre gondolok). Míg végigolvasni hasznos a kódot, de sokat segít az értelmezésben, ha egy alapszintű dokumentáció létezik, pl. nem 2 hét megismerni a működését a terméknek, hanem 2 nap.
Míg mondjuk egy szimpla weblapnál/webalkalmazásnál elég lehet a "kód önmagát dokumentálja" szemlélet, egy összetettebb rendszerben már messze áll az elvárható szinttől.
Üdv,
LuiseX
- A hozzászóláshoz be kell jelentkezni
A madártávlati fejlesztőknek szóló funkcionális leírás simán lehet a repoban egy doc könyvtárban struktúrált módon (HTML, Markdown, TeX, stb)
Weird részeknek meg ideális esetben nem kéne a kódban lennie, code review mindenképpen fogja már meg ezeket! Ha ronda haxxolásról van szó, akkor mondjuk, hogy lehet esetleg valami komment mellette, de egy ilyen kódrészlet becsekkelése azonnal szükséges volna, hogy magával vonjon egy "Refactor weird class" taskot, mert nyilvánvaló, hogy design szinten elcseszett dologról lehet szó, különben nem lenne szükség haxxolásra.
--
"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
- A hozzászóláshoz be kell jelentkezni
+1
- A hozzászóláshoz be kell jelentkezni
Felhasználói, telepítési és üzemeltetési dokumentáció külön file-ban a megrendelő által kért formátumban.
Fejlesztői dokumentációt forrásban (javadoc, vagy xml doc) amiből lehet generálni doxygen-nel emészthetőbb formát ha valakinek kell.
- A hozzászóláshoz be kell jelentkezni
A főnökök szóban tájékoztatva a legfontosabb tulajdonságokról, illetve ezeket rendszerint a szerződés is tartalmazza.
A felhasználó betanítva, menüpontként doksi, illetve egy jegyzetfüzet menüpont,
ahová a felhasználó saját gondolatait feljegyezheti a programmal kapcsolatban.
A forráskódot mindig adom azzal, hogy csak és kizárólag akadályoztatásom esetén (pl meghaltam) és csak és kizárólag szervizelési céllal használható (== a program nem a szerződésben megadott paraméterek szerint működik), 3. félnek át nem adható.
kb így
> Sol omnibus lucet.
- A hozzászóláshoz be kell jelentkezni
Általában PDF, de a Wiki is jó dolog, persze ott van PDF-ben a Wiki is, mert valaki azt jobban bírja, ha külön is meg tudja nyitni, mert az olyan professzionális.
--
A főnököm mindig megtartja amit ígér, ha pénzt ígér azt is!
- A hozzászóláshoz be kell jelentkezni
Magán tudásbázis --> Wiki
Hivatalos céges, benyújtható --> .doc, mert azt szeretik
- A hozzászóláshoz be kell jelentkezni
Wiki és/vagy programból elérhető és/vagy forráskódban.
- A hozzászóláshoz be kell jelentkezni
Nem írok, mert a felhasználóim gondolatolvasók.
- A hozzászóláshoz be kell jelentkezni
+1
És különben is, a programozás művészet, a művészetet nem érteni hanem érezni kell, hát érezzék! :)
- A hozzászóláshoz be kell jelentkezni
+1
- A hozzászóláshoz be kell jelentkezni
(-::
> Sol omnibus lucet.
- A hozzászóláshoz be kell jelentkezni
Csak akkor írok, ha a megrendelő igényli és akkor doc-ban, konvertálva PDF-be.
Illetve a forráskódot szinte mindig szoktam kommentálni, magam, vagy más fejlesztők számára.
- A hozzászóláshoz be kell jelentkezni
Csak a markdown
- A hozzászóláshoz be kell jelentkezni
ODT-ben (LibreOffice) írok felhasználói kézikönyvet, saját konverter átalakítja CHM helppé és nyomtatható PDF-fé.
- A hozzászóláshoz be kell jelentkezni
forraskodba irt Doxygen, az melyik lehetoseg? :D
- A hozzászóláshoz be kell jelentkezni
A felesleges. :P
Szerintem egy code compass sokkal többet ér.
--
"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
- A hozzászóláshoz be kell jelentkezni
tehat szerinted dokumentaciot irni felesleges?
- A hozzászóláshoz be kell jelentkezni
wiki
--
Allitsuk meg Andorrat!
- A hozzászóláshoz be kell jelentkezni
Devel fele Confluence wiki. Ebben vannak:
- a user story-k, acceptance criteria-kkal, érintett képernyőkkel és szakindoklással (mindjárt megérted, miért)
- a flow ábrák
- a scenario-k
- az adatdefiníciók
- képernyőnkénti bontásban
-- mi miért van úgy, visszautalás user story-ra
-- pszeudokód minden interakcióra
-- változó életciklus kezelések
-- szélsőesetek, hibaüzenetek
Confluence-ben kommentelhető minden szó, a képeken komment pont helyezhető el, a képek nagyíthatóak (differenciálspecinél, amikor a régi és az új képernyő egymás mellett van, nagyon hasznos), ez az utóbbi amit a gDocs nem tud.
Természetesen a vezetők, megrendelők kapnak pdf-et is, de a technikai emberek a kommentelhetőség meg az "egy, mindig aktualizált változat" miatt accountot kapnak.
Nem ez az egyetlen doksink (sok projektmenedzsment zajlik belül marvel prototípusok kommentjeiként pl, azon zajlik a UX-UI átadás nagy része), de a programozók fele minden ebben van.
- A hozzászóláshoz be kell jelentkezni
Egyébként van rá külön személy a cégnél. Ők megtanítottak minket DITA-ban doksi inputot adni, mi megtanítottuk őket git-et használni. Azóta a fejlesztők pull request-ben adják a nyers doksit, a doksírók meg összeszerkesztik (illetve lefordítják angolról angolra, és megpróbálják érthetőre átírni :).
---
Régóta vágyok én, az androidok mezonkincsére már!
- A hozzászóláshoz be kell jelentkezni
Van wikin is, a menedzsmentnek csak az, a diagramok is ott vannak és a legtöbb kapcsolódó dolog. Meg van docstringből generált dokumentáció is. Ha az Doxygen, akkor általában van call/caller gráf is, ha Sphinx akkor nincs.
- A hozzászóláshoz be kell jelentkezni
Kb 1:1:1:1 aranyban: latex+pdf, --(long-)help | help2man | man, wiki, semmi (szóban, sehogy, oldd meg, stb)
- A hozzászóláshoz be kell jelentkezni