Existuje několik dobrých příkladů dobře zdokumentovaného kódu, například java api. Mnoho kódů ve veřejných projektech, jako je git a interní projekty společností, je však špatně zdokumentováno a není příliš přívětivé pro nováčky.

Ve všech svých stincích vývoje softwaru jsem se musel vypořádat se špatně zdokumentovaným kódem. Všiml jsem si následujících věcí –

  1. Malé nebo žádné komentáře v kódu.
  2. Názvy metod a proměnných nepopisují samy sebe.
  3. O tom, jak kód zapadá do systému nebo obchodních procesů, není k dispozici žádná dokumentace.
  4. Najímání špatných vývojářů nebo mentorování těch dobrých. Nemohou psát jednoduchý a čistý kód. Proto je pro kohokoli, včetně vývojáře, zdokumentovat kód obtížné nebo nemožné.

Ve výsledku jsem musel projít spoustou kódovat a mluvit s mnoha lidmi, aby se něco naučili. Cítím, že to promarňuje čas každého. Vytváří také potřebu relací přenosu KT / znalostí pro nováčky v projektu.

Zjistil jsem, že dokumentaci není věnována pozornost, kterou si zaslouží, z následujících důvodů:

  1. Lenost.
  2. Vývojáři nechtějí dělat nic jiného než kód.
  3. Zabezpečení úlohy. (Pokud vašemu kódu nikdo nerozumí snadno, možná nebudete snadno vyměnitelní.)
  4. Obtížné termíny ponechávají málo času na dokumentaci.

Zajímalo by mě, jestli existuje způsob, jak podpořit a prosazovat osvědčené postupy dokumentace ve společnosti nebo projektu. Jaké jsou strategie použít k vytvoření slušné dokumentace pro systémy a kód jakéhokoli projektu bez ohledu na jeho složitost? Existují nějaké dobré příklady, kdy je potřeba minimální nebo žádná dokumentace?

IMHO, mám pocit, že bychom měli mít přezkoumání dokumentace po dodání projektu. Pokud to není jednoduché, stručné, názorné a uživatelsky přívětivé, je za něj odpovědný vývojář nebo technik technické dokumentace, který je oprávněn jej opravit. Ani neočekávám, že lidé budou dělat dokumentaci, ne doufám, že to bude uživatelsky přívětivé jako první knihy, ale očekávám, že to eliminuje potřebu hodiny analýzy a nehospodárné relace KT.

Existuje způsob, jak toto šílenství ukončit nebo zmírnit? Možná vývoj „na základě dokumentů“?

Komentáře

  • Existuje ještě další důvod, proč často neexistuje řádná dokumentace: Je velmi těžké napsat dobrou dokumentaci, která ‚ pouze parafrázuje kód v angličtině, ale popisuje proč je kód navržen / napsán tímto způsobem. Potřeba těchto informací je zřejmá až měsíce po , kdy by měla být zapsána.
  • Další závažný důvod: mnoho vývojářů používá angličtinu jako druhý jazyk a / nebo anglicky píše špatně . Mohli byste je přinutit, aby pro metodu napsali jednorázovou linii, ale pokud chcete dobrou dokumentaci, měli byste být připraveni ji zaplatit a najmout si k tomu specialisty.

Odpověď

Jak dokumentovat kód?

Již máte nápovědu: podívejte se, jak je dokumentováno rozhraní Java API.

Obecněji řečeno, pro každý projekt neexistuje žádná jedinečná sada pravidel. Když pracuji na důležitých obchodních velkých projektech, dokumentace nemá nic společného s tím, co bych napsal pro malou knihovnu otevřeného zdroje, což zase nemá nic společného s dokumentací mého osobního projektu středního rozsahu .

Proč mnoho open source projektů není dobře zdokumentováno?

Protože většinu open source projektů vytvářejí lidé, kteří do těchto projektů přispívají, protože je to zábava. Většina programátorů a vývojářů zvažuje že psaní dokumentace není dost zábavné dělat zdarma.

Proč mnoho projektů s uzavřeným zdrojem nejsou zdokumentovány dobře?

Protože (1) stojí za to obrovské peníze (1) napsat dobrou dokumentaci a (2) ji udržovat.

  1. Okamžité náklady (náklady na vypracování dokumentace) jsou pro zúčastněné strany jasně viditelné: pokud váš tým požádá o další dva měsíce strávené dokumentováním projektu, je třeba zaplatit další dva měsíce platu.

  2. The lo Termínové náklady (náklady na údržbu dokumentace) jsou pro manažery také snadno patrné a jsou často prvním cílem, když musí snížit náklady nebo zkrátit zpoždění. To způsobuje další problém se zastaralou dokumentací, který se rychle stává zbytečným a jeho aktualizace je extrémně nákladná.

  3. Dlouhodobé úspory (úspory z toho, že nebudete muset ztrácet pár dní zkoumáním starší kód, jen aby pochopili základní věc, která měla být zdokumentována před lety) jsou na druhou stranu obtížně měřitelné, což potvrzuje pocit některých manažerů, že psaní a údržba dokumentace je ztráta času.

Často pozoruji, že:

  1. Na začátku je tým ochoten hodně dokumentovat.

  2. V průběhu času tlak na termíny a nedostatek zájmu ztěžují údržbu dokumentace.

  3. Několik měsíců později nová osoba, která se k projektu připojí prakticky, nemůže „použít dokumentaci, protože vůbec neodpovídá skutečnému systému.

  4. Všimněte si toho, že vedení obviňuje vývojáře za neudržování dokumentace; vývojáři žádají, aby jejich aktualizaci strávili několik týdnů.

    • Pokud na to vedení udělí několik týdnů, cyklus se opakuje.

    • Pokud vedení odmítne na základě předchozích zkušeností, pouze zvýší špatné zkušenosti, protože produktu chybí dokumentace, ale psaní a údržbě bylo věnováno několik měsíců.

Dokumentace by měla být nepřetržitým procesem, stejně jako testování. Strávte týden prostým kódováním několika tisíc LOC a návrat k testům a dokumentaci je velmi, velmi bolestivý.

Jak povzbudit tým k psaní dokumentace?

Podobně jako způsoby, jak přimět lidi, aby psali čistý kód, prováděli pravidelné refaktorování, používali návrhové vzory nebo přidali dostatek testů jednotek.

  • Vést příkladem. Pokud píšete dobrou dokumentaci, mohou to začít dělat i vaše páry.

  • Provádějte systematické kontroly kódu, včetně formálních kontrol kódu zaměřených na kontrolu dokumentace.

  • Pokud jsou někteří členové týmu zvláště antipatičtí k dobré dokumentaci (nebo vůbec k dokumentaci), proberte s nimi předmět soukromě, abyste pochopili, jaké překážky jim brání v psaní lepší dokumentace. Pokud obviňují nedostatek času, uvidíte zdroj problémů.

  • Zajistěte, aby přítomnost nebo nedostatek dokumentace byly měřitelné po dobu několika týdnů nebo měsíců, ale ne zaměřte se na to. Můžete například změřit počet řádků komentářů na LOC, ale nedělejte to jako trvalé měřítko, jinak vývojáři začnou psát dlouhé, ale nesmyslné komentáře, aby se zbavili nízkého skóre.

  • Použijte gamifikaci. Toto je spojeno s předchozím bodem.

  • Použijte pozitivní / negativní zesílení .

  • (Viz komentář od SJuan76 ) Považovat nedostatek komentářů za chyby. Například v sadě Visual Studio můžete zkontrolovat možnost generování dokumentace XML. Pokud také zkontrolujete, že se všechna varování považují za chyby, nedostatek komentáře v horní části třídy nebo metody zastaví kompilaci.

    Pokud jde o tři předchozí body, mělo by se použít toto s opatrností. Chvíli jsem to používal s obzvláště tvrdým týmem začínajících programátorů a skončilo to tak, že vyhovoval komentářům vyhovujícím StyleCop: 

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

které byly, hm …, nijak zvlášť užitečné.

Pamatujte si: nic automatizovaného vám nemůže pomoci určit špatné komentáře, když s vámi programátoři budou chtít bojovat. pomohou recenze a další lidské úkoly.

Existují nějaké dobré příklady, kdy je potřeba minimální nebo žádná dokumentace?

Dokumentace vysvětlující architekturu a design není zapotřebí:

  • U prototypu

  • U osobního projektu napsaného za několik hodin za účelem splnění úkolu, přičemž si lze být docela jisti, že tento projekt již nebude udržován,

  • Pro každý projekt, u kterého je zřejmé, vzhledem k malá velikost, spolu s obzvláště čistým kódem, že strávíte více času psaním dokumentace než všichni budoucí správci zkoumáním kódu.

Dokumentace v kódu (komentáře ke kódu) není podle některých vývojářů nutná, pokud je kód samodokumentující. Pro ně přítomnost komentářů není, s výjimkou ojedinělých případů, dobrým znamením, ale znamením, že kód nebyl dostatečně upraven, aby byl jasný bez nutnosti komentářů.

Mám pocit, že po doručení projektu bychom měli zkontrolovat dokumentaci.

Pokud je váš projekt doručen alespoň jednou týdně je to správná cesta. Pokud váš projekt není agilní a je dodáván v intervalech šesti měsíců, proveďte pravidelnější kontroly.

Komentáře

  • Komu jak povzbudit ‚, dodal bych, že mnoho IDE umožňuje upozornění na chybějící dokumentaci jako varování. Alternativně je možné provést statickou analýzu dokumentace na OSB (to by samo o sobě samozřejmě nestačilo).
  • @ SJuan76: Opravdu. Visual Studio může dokonce považovat nedostatek komentářů za chybu při kompilaci. Upravil jsem svou odpověď a přidal k tomu poznámku.
  • @ArseniMourzenko – četl jsem, že bychom mohli povzbudit nějakou dokumentaci v Agile přidáním příběhů k dokumentaci. Neměly by však blokovat ostatní příběhy, tj. Definice jiných příběhů hotových, nesmí zahrnovat dokončení dokumentačních příběhů. Jak to zní?
  • @ArseniMourzenko – rád bych k vaší odpovědi přidal další dva body. (1) V Jira atd. Neustále přidávejte úkol pro dokumentaci. (2) Nechte všechny dokumenty zkontrolovat dalšími 2 lidmi &, aby to zadali také jako úkol. Tímto způsobem bude lidem připomenuto, aby dokument & zabránil psaní dokumentů nízké kvality (kvůli kontrole). Pokud to ‚ neupřednostníte &, nezkontrolujete to, bude to špatné. Vím, že Amazon dělá spoustu dokumentů & recenzí dokumentů, možná až příliš.

Odpovědět

Myslím, že byste měli rozlišovat mezi komentáři a dokumentací. Zatímco komentáře jsou popisné, postrádají konzistenci, jsou rozptýleny po celém kódu. Komentáře by nikdy neměly kompenzovat kód, který sám o sobě dostatečně nepopisuje, místo toho by měl naznačovat ostatním programátorům složité části.

To, zda by měl být kód dokumentován, závisí na rozsahu projektu. Určitě existují lidé, kteří věří, že vše by mělo být zdokumentováno a zdá se být snadné tuto myšlenku ospravedlnit, protože kdo by se odvážil postavit proti dokumentovat znalosti? Naštěstí vývoj softwaru není věda a svět se nezhroutí, pokud podrobnosti za vaším malým programem budou nejasné. Nyní, pokud jde o profesionální software pro použití mnoha vývojáři, ano, samozřejmě byste měli dokumentovat svůj kód. Ale pokud jste v pozici kódovat na této úrovni, pak byste to samozřejmě věděli.

tl; dr

Pokud požadujete, aby byl každý projekt dobře zdokumentován, pak požadujete příliš mnoho .

Komentáře

  • Fortunately software development is not science Řekněte mi prosím více o tom, proč tomu věříte.
  • @Borat – Vývoj softwaru je inženýrská disciplína, což znamená, že využívá nástroje poskytované vědou.
  • Nežádám, aby bylo vše dokumentováno. Mělo by to být dost na to, abych poskytl přehled na vysoké úrovni o tom, co systém a kód dělá. Např. prosím, řekněte mi, jak používat můj televizor. Nezajímá mě ‚ jestli používá LCD, CRT, Vakuové trubice nebo polovodičová zařízení k dokončení práce . Pokud opravář chce tyto informace, vytvořte pro něj samostatnou dokumentaci.
  • Pokud chcete přehled na vysoké úrovni, pak stačí identifikátor. Stejně jako tlačítko na vašem televizoru může mít štítek “ na „. Takže žádáte o podrobnosti na nízké úrovni.
  • @LeopoldAsperger: Myslím, že Borat mluví o dokumentování architektury a designu, nikoli metod ve třídách.

Napsat komentář

Vaše e-mailová adresa nebude zveřejněna. Vyžadované informace jsou označeny *