Dokumentace ke zdrojovým kódům

Thomas

Dokumentace ke zdrojovým kódům
« kdy: 29. 11. 2012, 12:33:46 »
Ahoj,

netuší někdo jestli je potřeba do technické dokumentace k nějakému programu psát i kompletní dokumentaci ke zdrojovým kódům? Vůbec se mi do toho nechce. A nemáte k dispozici nějaký proform jak by měla technická dokumentace vypadat?

Díky
« Poslední změna: 29. 11. 2012, 20:20:43 od Petr Krčmář »


Markus

Re:Technická Dokumentace
« Odpověď #1 kdy: 29. 11. 2012, 12:55:50 »
Myslím, že ke svému vlastnímu Hellowordl.c jí vážně psát nemusíš, až budeš dělat větší projekty, uvidíš, co po tobě kdo žádá.

Thomas

Re:Technická Dokumentace
« Odpověď #2 kdy: 29. 11. 2012, 13:07:20 »
hmm fakt inteligentní odpověď. Jedná se o komerční produkt.

Re:Technická Dokumentace
« Odpověď #3 kdy: 29. 11. 2012, 13:11:45 »
hmm fakt inteligentní odpověď.
O dost inteligentnější než otázka.

Ivan

Re:Technická Dokumentace
« Odpověď #4 kdy: 29. 11. 2012, 13:50:32 »
Jedná se o komerční produkt.
Pokud se jedna o komercni produkt, tak ma nejspis tvuj zamestnavatel nejakou sablonu, anebo dokonce dodrzuje nejaky "standart" ze ktereho vyplyva jak ma dokumentace vypadat.


M.

Re:Technická Dokumentace
« Odpověď #5 kdy: 29. 11. 2012, 14:05:41 »
netuší někdo jestli je potřeba do technické dokumentace k nějakému programu psát i kompletní dokumentaci ke zdrojovým kódům? Vůbec se mi do toho nechce. A nemáte k dispozici nějaký proform jak by měla technická dokumentace vypadat?

To by blo na dlouho, prvně máme hodnocení zadnaého zadání, jeho přepis do formální algebraického jazyka, potom dokazovaní shody převody, že převod i zdání je jendoznačné, dále dokazování, že zadání neodporuje fyzikálním zákonům a je v e shodě s teorií, hodnocení úplnosti, hodnocení a dokaování jednoznačné algoritmizovatlenosti zadání, dále pro zvolené vývojové prostředí dokazování, že jde provést převod z fomalního jazyka do programovacího jazyka, opět dokazování jendoznačné převoditelnosti, ověřování, shodné přeložitelnosit a zpětného převodu, bokem hodnocení spolehlivosti vývojového prostředí, analýza zjištěných chyb a chybovosti vývojového prostředí, pak to konečně můžeme přeložit, dokazování funkčnosti a ověřování nepoužití zakázaných konstrukcí a postupů, zdokumentoaní všech vstupů a výstupů, popis věech vnitřních algoritmů, následuje popisy všech testů a vyjadřovaní shody testů a jak velké procento všech možných stavů systémů to popisuje a tak dále.....
Aneb klasické kolečko na pár tisíc stránek textu, než napíši program int main(void){printf("Bla\r\n"); return 0;}, pokud zadavatel vyžaduje vývoj v souladu s normami pro psaní software s vlivem na jadernou bezpečnost... :-)

Diskobolos

Re:Technická Dokumentace
« Odpověď #6 kdy: 29. 11. 2012, 14:09:44 »
Technickou doukumentaci kódu a ne návod? Piš kód tak, aby obsahoval dokumentační/komentářové anotace ala phpdoc.org. Pak existuje spousta nástrojů na dělání reportů z těchto komentářů (výstupy do html, pdf, doc, atd...). Takový manuál je vždy aktuální a po letech se hodí i samotnému autorovi.

Sten

Re:Technická Dokumentace
« Odpověď #7 kdy: 29. 11. 2012, 15:09:42 »
Ahoj,

netuší někdo jestli je potřeba do technické dokumentace k nějakému programu psát i kompletní dokumentaci ke zdrojovým kódům? Vůbec se mi do toho nechce. A nemáte k dispozici nějaký proform jak by měla technická dokumentace vypadat?

Díky

No rozhodně se hodí, když je tam popsané API (třídy a metody a jejich parametry), běžné call flow, popis XML dokumentů či proprietárních protokolů ap. Popis přímo samotného kódu do technické dokumentace IMO nepatří (s výjimkou popisu bugů a todo).

De facto standardem jsou Doxygen a Javadoc (pro Javu). Já osobně preferuji Doxygen všude, protože je nejen kompatibilní s Javadoc, ale taky umí vytvářet pomocné stránky (popisy protokolů, tutoriály ap.) a výsledná dokumentace může být velmi komplexní, přitom ale je velmi snadná na sepsání, a co lze, to zůstává přímo u kódu.

Re:Technická Dokumentace
« Odpověď #8 kdy: 29. 11. 2012, 18:25:06 »
Ahoj,

netuší někdo jestli je potřeba do technické dokumentace k nějakému programu psát i kompletní dokumentaci ke zdrojovým kódům? Vůbec se mi do toho nechce. A nemáte k dispozici nějaký proform jak by měla technická dokumentace vypadat?

Díky

jasne ze netreba, ale ked zmenis zamestnanie tak ten kto po tebe nastupi dostane strasnu chut ti polamat ruky :D

Ivorne

Re:Dokumentace ke zdrojovým kódům
« Odpověď #9 kdy: 29. 11. 2012, 20:30:28 »
Celé se to samozřejmě odvíjí od toho, jaké nároky má software a jeho technická dokumentace splňovat. První věc je, pro koho má technická dokumentace být. Jestli pro uživatele, nebo pro vývojáře systémů začleňujících váš software nebo pro vývojáře vašeho softwaru. Dále je pak třeba odhadnout trvanlivost software - tedy jestli je to spíše naprasená rychlovka, která se nebude měnit a za pár let se vymění, nebo spíše robustnější software určený pro postupný vývoj a přizpůsobování novým požadavkům. A nakonec je třeba znát požadavky na bezpečnost a spolehlivost - viz příspěvek od M. Je značný rozdíl mezi tím, jestli děláte blogovací redakční systém nebo software pro řízení jaderné elektrárny.

Když tohle zjistíte a promyslíte, tak by z toho mělo aspoň částečně vyplynout, co je potřeba dávat do technické dokumentace.

Pokud nevysvětlíte, co je to za software, tak vám těžko někdo poradí něco konkrétnějšího.