Dokumentace kódu:Průvodce pro začátečníky🎯

V tomto blogu se rychle podíváme na to, jak zdokumentovat kód. Než se pustíme do toho, jak správně dokumentovat kód, pojďme si nejprve porozumět Proč je nutné dokumentovat váš kód?

Jak získáváme více zkušeností v oblasti technologií nebo vývoje softwaru, všimneme si, že mnohem více času trávíme čtením kódu než jeho vývojem. A to může zahrnovat čtení předchozích verzí vašeho vlastního kódu, hodnocení dokumentace někoho jiného ve vašem týmu nebo analýzu kódu z knihoven třetích stran a jejich příkladů.

V důsledku toho si uvědomujeme, že náš kód by měl být čitelnější a udržovatelnější, abychom zkrátili čas potřebný k jeho pochopení! Podíváme se na několik triků a tipů, které vám pomohou učinit váš kód čitelnějším a lépe zdokumentovaným.

1. Přidejte ke svému kódu komentáře

Účelem přidávání komentářů do kódu je poskytnout srozumitelný popis toho, co váš kód dělá.

Při komentování kódu mějte na paměti následující:
A. Neopakujte jednoduše, co kód dělá.
b. Popište proč . Proč kód dělá to, co dělá? Jaký je obchodní předpoklad nebo krok algoritmu?
C. Formátujte své komentáře pro maximální čitelnost. Řádně je zalepte, v případě potřeby ponechte mezery
d. Zkuste využít nástroje/rozšíření VS kódu.

několik komentářů GhostDoc a Add JSDoc

Osobně preferuji Add JSDoc pro komentování, je to super snadné použití.

Přečtěte si tento článek na webu MSDN o psaní efektivních komentářů

2. Napište testovací případy :

Většina vývojářů píše pro svůj kód testy jednotek, aby bylo zajištěno, že kód funguje správně . To pomáhá odhalit chyby a chránit se před nimi v budoucnu.

V podstatě testovací případy vám poskytují představu o tom, jak by se měl kód chovat, a můžeme si být jisti, že to nezpůsobí žádné problémy ve výrobě..

Pro psaní testovacích případů používejte nástroje/knihovny specifické pro jazyk/rámec. Preferuji Jest pro NodeJS a React. Je rychlý a bezpečný a umožňuje snadné zesměšňování a pokrytí kódem

3. Poskytněte vhodnou zprávu odevzdání git.

Správné zprávy odevzdání git jsou užitečné v následujících ohledech:
A. Zvyšuje přehlednost vznesených žádostí o stažení (PR).
b. Je to klíč k efektivnímu ladění v týmu
C. Usnadňuje sledování implementace

Existuje skvělý článek o zprávě commitu Git

Jak napsat dobrou zprávu o odevzdání

Tip:Přidejte id úkolu/problému do zprávy odevzdání git, pomůže to identifikovat přesnou funkci, která byla odeslána, a bude snadné ji vysledovat. A zprávy git commit by měly být imperativ přítomný čas

např. #task_id commit_message #3201 přidat přihlašovací údaje Google

4. Udržujte správný soubor Readme

Je to dokumentace s pokyny, jak používat projekt. Obvykle obsahuje pokyny k instalaci a spuštění projektu. Nečinný readme by měl mít
A. Název projektu
b. Popis projektu
C. Jak nainstalovat a spustit projekt
d. Vysvětlení struktury složek a výzvy
E. Známé problémy a kredity
F. Licence a verze

Rozšíření pro vytváření špičkového souboru Readme. :Náhled Markdown Enhanced

5. Napište vlastní dokumentovaný čistý kód

Existuje důvod, proč jsem si to nechal na konec, protože jsem to chtěl zdůraznit jako nejdůležitější bod ze všech.

Existuje několik věcí, které by vývojář měl mít při psaní kódu na úrovni produkce vždy na paměti:

  1. Vytvořte logickou a spravovatelnou strukturu složek (pro React viz Doporučené postupy struktury projektu React pro škálovatelné aplikace)
  2. Dodržování smysluplných konvencí pojmenování souborů, proměnných a funkcí v celém projektu
  3. Předcházení nadbytečného kódu:Zjistěte, který kód se opakuje, a zkuste jej zobecnit předáním proměnných argumentů.
  4. Komentování:Někdy vývojáři vytvoří opravdu složitou logiku a po několika měsících se dozvíme, co jsme udělali, ale stěží si vzpomeneme, proč jsme to udělali, takže je lepší, když napíšete nějaké komentáře, kdykoli to bude nutné.
  5. Formátování:Jedním ze způsobů, jak učinit váš kód čitelnějším, je formátovat kód a dodržovat stejné konvence/záměry v celém projektu. Pro formátování používám rozšíření prettierr.
  6. Často kontrolujte svůj kód:Pokud kódujete 8–10 hodin denně, zkuste věnovat 1–2 hodiny jeho kontrole, kde budete hledat vylepšení, optimalizaci, pracovat na složitosti (čas a prostor) a dokumentovat kód. To vám v budoucnu ušetří spoustu času a pomůže vám to růst mnohem lepšími způsoby. Osobně na to preferuji odpoledne.

Chcete-li lépe porozumět čistému kódu, přečtěte si tuto knihu.

Závěr

V této části jsme se podívali na to, jak napsat dokumentaci ke kódu, která vám pomůže učinit váš kód čitelnějším a dobře zdokumentovaným.

  • Přidejte ke svému kódu komentáře
  • Psaní testovacích případů
  • Poskytněte vhodnou zprávu odevzdání git.
  • Udržujte správný soubor Readme
  • Napište samostatně zdokumentovaný čistý kód

Celkově existuje mnoho dalších způsobů, jak dokumentovat svůj kód, použijte ten, který je podle vás nejlepší!

Pokud zde nějaký bod chybí, dejte nám vědět v sekci komentářů.