Když přemýšlíte o programování, je přirozené zaměřit se na témata, jako jsou jazyky, algoritmy a ladění. Technická dokumentace však může být stejně důležitá pro správné provedení.

Bez dobré dokumentace může utrpět opětovná použitelnost kódu. Uživatelé, kteří jsou v kódové základně noví, se mohou snadno ztratit nebo být frustrovaní, pokud dokumentace není na úplném začátku. Není důležité pouze rozumět tomu, co program dělá, ale také jak – nebo dokonce proč – to dělá.

Balíčky jako Pydoc pro Python a Javadoc pro Java pomáhají automatizací části procesu. Nástroj Godoc dělá totéž pro Go.

Co je Godoc?

Godoc je balíček Go, který vám umožňuje vytvářet, spravovat a používat dokumentaci Go „cestou Go“. Cesta Go je sada zásad, které byste jako programátor Go měli dodržovat, abyste zlepšili kvalitu kódu.

Pomocí Godoc můžete snadno číst dokumentaci a kód ostatních vývojářů. Můžete také automatizovat vytváření vlastní dokumentace a publikovat ji pomocí Godoc.

Godoc je podobný Javadoc, dokumentátor kódu pro Javu

instagram viewer
. Oba používají komentáře a kód v modulech ke generování dokumentace. A oba nástroje strukturují tuto dokumentaci v HTML, takže si ji můžete prohlédnout v prohlížeči.

Začínáme s Godoc

Použití Godoc je snadné. Chcete-li začít, nainstalujte balíček Godoc z webu golang pomocí tohoto příkazu:

jít získat golang.org/x/tools/cmd/godoc

Spuštěním tohoto příkazu se Godoc nainstaluje do vámi určeného pracovního prostoru. Po dokončení byste měli být schopni spustit godoc příkaz v terminálu. Pokud se při instalaci vyskytnou nějaké chyby, zkuste aktualizovat Go na nejnovější verzi.

Godoc hledá jednořádkové a víceřádkové komentáře, které má zahrnout do dokumentace, kterou generuje.

Ujistěte se, že kód naformátujete způsobem Go, jak je vysvětleno v publikaci Effective Go týmem Go pro dosažení nejlepších výsledků.

Zde je příklad použití jednořádkových komentářů ve stylu C++:

// User je struct model obsahující
typ Uživatel strukturovat {

}

Můžete také použít komentáře bloku ve stylu C:

/* 
Uživatel je vlastní datová struktura

Zde můžete vložit libovolný text a server Godoc jej při spuštění naformátuje.
*/
typ Uživatel strukturovat {

}

Ve výše uvedených komentářích „Uživatel“ začíná věty, protože komentář popisuje, co struktura uživatele dělá. Toto je jedno z mnoha témat, o kterých Go way pojednává. Začátek dokumentačních vět užitečným názvem je zásadní, protože první věta se objeví v seznamu balíčků.

Spuštění serveru Godoc

Jakmile svůj kód okomentujete, můžete spustit godoc příkaz ve vašem terminálu z adresáře kódu vašeho projektu.

Vývojáři Go obvykle používají port 6060 hostit dokumentaci. Toto je příkaz pro spuštění serveru Godoc na tomto portu:

godoc -http=:6060 

Výše uvedený příkaz hostuje dokumentaci vašeho kódu na localhost nebo 127.0.0.1. Port nemusí být 6060; godoc poběží na jakémkoli neobsazeném portu. Vždy je však nejlepší dodržovat konvence dokumentace Go.

Po spuštění příkazu si můžete prohlédnout dokumentaci v prohlížeči na adrese localhost: 6060. Čas, který Godoc potřebuje k vytvoření vaší dokumentace, bude záviset na její velikosti a složitosti.

Níže uvedený kód se drží způsobu Go, v tomto případě pomocí jednořádkových komentářů.

// název balíčku
balík uživatel

// fmt je zodpovědný za formátování
import (
"fmt"
)

// Uživatel je struktura lidských dat
typ Uživatel strukturovat {
Stáří int
název tětiva
}

funchlavní() {
// člověk je inicializací uživatelské struktury
člověk := Uživatel {
Stáří: 0,
Jméno: "osoba",
}

fmt. Println (člověk. Mluvit())
}

// Talk je metoda uživatelské struktury
func(uživatel přijímače)Mluvit()tětiva {
vrátit se "Každý uživatel může něco říct!"
}

Pokud spustíte Godoc na modulu kódu výše, měli byste vidět výstup vypadat nějak takto:

Všimněte si, že je ve známém formátu, podobném tomu, který najdete na oficiálních webových stránkách dokumentace Go.

Godoc používá komentář před deklarací balíčku jako Přehled. Ujistěte se, že tento komentář popisuje, co váš program dělá.

The Index obsahuje odkazy na deklarace typu a metody, takže k nim můžete rychle přejít.

Godoc také poskytuje funkce pro prohlížení zdrojového kódu, který tvoří balíček v Soubory balíčku sekce.

Zlepšení vaší dokumentace pomocí Godoc

Do své dokumentace Godoc můžete zahrnout více než jen prostý text. Můžete přidat adresy URL, na které bude Godoc generovat odkazy, a strukturovat vaše komentáře do odstavců.

Pokud chcete odkazovat na zdroj, napište URL do komentáře a Godoc to rozpozná a přidá odkaz. U odstavců ponechte prázdný řádek komentáře.

// Hlavní balíček
balík hlavní

// Dokument představuje běžný dokument.
//
// Odkaz na https://google.com
typ Dokument strukturovat {
stránky int
Reference tětiva
podepsaný bool
}

// Write zapíše nový dokument do úložiště
//
// O psaní se můžete dozvědět na Wikipedia.com
funcNapsat() {

}

Všimněte si, že Godoc vyžaduje, abyste zapsali adresy URL v plném rozsahu, aby je mohl propojit. V tomto příkladu adresa URL Google zahrnuje https:// prefix, takže Godoc na něj přidá odkaz. Protože doména Wikipedie není sama o sobě úplnou URL, Godoc ji nechá být.

Zde je několik nejlepších zásad, které je třeba použít při dokumentování kódu Go:

  • Udržujte svou dokumentaci jednoduchou a stručnou.
  • Větu funkcí, typů a deklarací proměnných začněte jejich názvy.
  • Začněte řádek s odsazením, abyste jej předem naformátovali jako kód.
  • Komentáře začínající „BUG(jméno)“ jako „BUG(joe): Tohle nefunguje“ jsou speciální. Godoc je rozpozná jako chyby a nahlásí je ve své vlastní sekci dokumentace.

Godoc vám pomůže s dokumentací

Pomocí Godoc můžete být produktivnější a nemusíte se starat o námahu ruční dokumentace vašich programů.

Svou dokumentaci byste měli udržovat přesnou, podrobnou a k věci, aby ji vaše cílové publikum snáze četlo a porozumělo. Je také důležité, abyste při úpravách programu udržovali komentáře ke kódu aktuální.

Další informace o používání Godoc naleznete v dokumentaci k balíčku Godoc.