Komentáře
- Uveďte prosím, který jazyk chcete dokumentovat, standardy a nástroje se mezi jazyky liší. .
- Začněte tímto: Co měl váš software vyřešit / udělat? Nejprve zdokumentujte kroky, jak to to dělá.
- Vyhledejte stávající kód ve stávajících projektech open source. Přečtěte si prosím stávající kód. Pak to porovnejte s tím vaším. Nakonec se zeptejte konkrétních otázek na základě kódu, který jste našli.
Odpovědět
Měli byste zdokumentovat:
- záměr, proč;
a
- co nemusí být zřejmé, jak.
Proč jste optimalizovali tento bit, k čemu přesně je tato zkratka, jaký je výsledek, který očekáváte, jaký je požadavek, důvod, proč tam je na prvním místě, kam se tato data posílají, odkud máte vstup, pokud je to vícevláknové, vysvětlete model, pokud existuje databáze, vysvětlete schéma, odkazy, proč …
Nezdokumentujte to, co je zřejmé. Pokud jde o prezentaci, existuje mnoho způsobů, jak toho dosáhnout. Já osobně mám rád vložené komentáře (jsem starší programátor a tehdy jsme neměli přepychové nástroje – plus já prostě to považuji za jednoduché a přímé). Pokud chcete něco fantastického, ujistěte se, že to nespotřebovává příliš mnoho času, nebo to velmi pravděpodobně brzy opustíte.
Komentáře
- Záměr je často nejužitečnější věc, mohu se podívat na kód a pochopit, co dělá, ale pochopit, proč to vývojář udělal tímto způsobem, může být velmi užitečné.
Odpověď
Přečtěte si svůj vlastní kód, který jste napsali před 2 nebo více lety.
Zeptejte se sami sebe, jaké typy věcí jsou nejasné, a nechte se škrábat po hlavě při čtení. Tyto typy věcí (ať už jsou jakékoli, u různých programátorů se budou lišit) jsou to, co chcete začít dokumentovat jako první na každém novém kódu, který vyvinete, nebo na starém kódu, který přepíšete / znovu použijete. Jakékoli formátování, které zpomalí vaše porozumění , změna.
Nebo za 2 roky …
Odpověď
Jedna věc, kterou byste měli zahrnout je závislosti. Pokud funkce spoléhá na něco z támhle , pak doc co to je, kde tam je a proč.
Odpověď
Protože používáte PHP, PHPDoc by bylo dobrým místem pro začátek. Svou dokumentaci API můžete vytvořit přímo ve zdroji a pak použít stejný formát k psaní výukových programů a uživatelské dokumentace. Získáte také určitou flexibilitu, pokud jde o výstupní formát.
Odpověď
Vždy začnu psát kód tak, že nejprve napíšu své komentáře. Popište průběh programu a začněte si uvědomovat, co je třeba komentovat a co ne. Poté, co začnete psát kód, ozdobíte části, které vyžadují další vysvětlení, a upřesníte části, které se samy dokumentují.
Po dokončení každé třídy, funkce nebo metody se vrátím a přidám komentáře pro generátor dokumentů, jako je doxygen nebo PHPDoc. Získáte tak skutečnou dokumentaci API.
V závislosti na tom, kdo můj kód spotřebuje, napíšu formální popis dokumentu operace buď v LaTeXu nebo Wordu.
Odpověď
Doxygen pokrývá většinu jazyků. Budete muset strávit nějaký čas porozuměním syntaxi, ale hlavním problémem je to, co dokumentovat. S každou funkcí zacházejte jako s černou skříní. Dokumentujte, co jde dovnitř a co jde ven. Dokumentujte, jaké chyby zachycuje, ať už args mohou mít hodnotu null, zda může vrátit hodnotu null.
Pamatujte si, že za pár měsíců nebudete moci zjistit, co sakra funkce dělá. Jen si šetříte čas.