Amikor a programozásra gondol, természetes, hogy olyan témákra összpontosít, mint a nyelvek, algoritmusok és hibakeresés. De a műszaki dokumentáció ugyanolyan fontos lehet a helyes megoldáshoz.
Megfelelő dokumentáció nélkül a kód újrafelhasználhatósága károsodhat. A kódbázisban újonc felhasználók könnyen eltévedhetnek vagy frusztrálttá válhatnak, ha a dokumentáció nem ér fel teljesen. Nemcsak az a fontos, hogy megértsük, mit csinál egy program, hanem azt is, hogyan – vagy akár miért – csinálja.
Az olyan csomagok, mint a Pydoc for Python és a Javadoc for Java, segítenek a folyamat egy részének automatizálásában. A Godoc eszköz ugyanezt teszi a Go esetében is.
Mi az a Godoc?
A Godoc egy Go csomag, amely lehetővé teszi a Go dokumentáció létrehozását, kezelését és használatát a „Go way” módon. A Go way egy olyan alapelv, amelyet Go programozóként követnie kell a kód minőségének javítása érdekében.
A Godoc segítségével könnyedén elolvashatja más fejlesztők dokumentációját és kódját. Automatizálhatja saját dokumentációjának létrehozását és közzéteheti a Godoc segítségével.
Godoc hasonló Javadoc, a Java kóddokumentátora. Mindkettő megjegyzéseket és kódot használ a modulokban a dokumentáció létrehozásához. Mindkét eszköz HTML-ben strukturálja a dokumentációt, így böngészőben is megtekintheti.
A Godoc használatának megkezdése
A Godoc használata egyszerű. Kezdésként telepítse a Godoc csomagot a golang webhelyről a következő paranccsal:
megy töltse le a golang.org/x/tools/cmd/godoc fájlt
A parancs futtatása telepíti a Godoc-ot a megadott munkaterületre. Ha elkészült, képesnek kell lennie arra, hogy futtassa a goddoc parancsot egy terminálban. Ha hibákat észlel a telepítés során, próbálja meg frissíteni az Ugrás egy újabb verzióra.
A Godoc egy- és többsoros megjegyzéseket keres, amelyeket belefoglalhat az általa generált dokumentációba.
Ügyeljen arra, hogy a kódot Go módon formázza, ahogyan azt a fejezetben leírtuk az Effective Go kiadvány a Go csapat a legjobb eredmények érdekében.
Íme egy példa a C++ stílusú egysoros megjegyzések használatára:
// A User egy olyan struktúra modell, amely tartalmazza
típus Felhasználó struct {
}
Használhat C-stílusú blokkos megjegyzéseket is:
/*
A felhasználó egy egyéni adatstruktúraBármilyen szöveget beilleszthet ide, és a Godoc szerver formázza azt, amikor futtatja.
*/
típus Felhasználó struct {
}
A fenti megjegyzésekben a „Felhasználó” kezdi a mondatokat, mert a megjegyzés leírja, hogy mit csinál a User struktúra. Ez az egyik a sok téma közül, amelyeket a Go way tárgyal. A dokumentációs mondatok hasznos névvel való kezdése kulcsfontosságú, mivel az első mondat megjelenik a csomaglistában.
Godoc szerver futtatása
Miután kommentálta a kódot, futtathatja a goddoc parancsot a terminálban, a projekt kódkönyvtárából.
A Go fejlesztői hagyományosan portot használnak 6060 a dokumentáció befogadására. Ez a parancs a Godoc szerver futtatásához azon a porton:
godoc -http=:6060
A fenti parancs tárolja a kóddokumentációt localhost vagy 127.0.0.1. A portnak nem kell 6060-nak lennie; A godoc minden szabad porton futni fog. Azonban mindig a legjobb, ha követi a Go dokumentációs konvencióit.
A parancs futtatása után megtekintheti a dokumentációt a böngészőben, ha felkeresi localhost: 6060. A Godoc-nak a dokumentáció elkészítéséhez szükséges idő a méretétől és összetettségétől függ.
Az alábbi kód betartja a Go módot, ebben az esetben egysoros megjegyzéseket használ.
// a csomag neve
csomag felhasználó// Az fmt a formázásért felelős
import (
"fmt"
)// A felhasználó emberi adatok struktúrája
típus Felhasználó struct {
Kor int
Név húr
}funcfő-() {
// A human a felhasználói struktúra inicializálása
human := Felhasználó {
Kor: 0,
Név: "személy",
}fmt. Println (ember. Beszélgetés())
}
// A Talk a User struktúra egyik metódusa
func(fogadó felhasználó)Beszélgetés()húr {
Visszatérés "Minden felhasználó mondjon valamit!"
}
Ha a Godoc-ot a fenti kódmodulon futtatja, a kimenetnek így kell kinéznie:
Figyelje meg, hogy ismerős formátuma, hasonlóan ahhoz, amit a Go hivatalos dokumentációs webhelyén talál.
A Godoc a csomagdeklarációt megelőző megjegyzést használja a Áttekintés. Győződjön meg arról, hogy ez a megjegyzés leírja a program működését.
Az Index hivatkozásokat tartalmaz a típusdeklarációkra és metódusokra, így gyorsan navigálhat hozzájuk.
A Godoc a csomagot alkotó forráskód megtekintésére is lehetőséget biztosít a Csomagfájlok szakasz.
A dokumentáció javítása a Godoc segítségével
A Godoc dokumentációjában nem csak egyszerű szöveget foglalhat. Hozzáadhat olyan URL-eket, amelyekhez a Godoc linkeket generál, és a megjegyzéseit bekezdésekbe szerkesztheti.
Ha egy forrásra szeretne hivatkozni, írja be az URL-t a megjegyzésébe, és a Godoc felismeri, és hozzáad egy hivatkozást. Bekezdések esetén hagyjon üres megjegyzéssort.
// Csomag fő
csomag fő-// A dokumentum egy normál dokumentumot jelent.
//
// Link ehhez https://google.com
típus Dokumentum struct {
oldalakat int
hivatkozások húr
aláírva bool
}// A Write új dokumentumot ír a tárolóba
//
// Az írásról a Wikipedia.com webhelyről tájékozódhat
funcÍr() {
}
Vegye figyelembe, hogy a Godoc megköveteli, hogy az URL-eket teljes egészében kiírja, hogy összekapcsolhassa őket. Ebben a példában a Google URL tartalmazza a https:// előtag, így Godoc hivatkozást ad hozzá. Mivel a Wikipédia domain önmagában nem teljes URL, a Godoc békén hagyja.
Íme néhány legjobb elv, amelyet a Go kód dokumentálásakor alkalmazni kell:
- A dokumentáció legyen egyszerű és tömör.
- Kezdje a függvények, típusok és változódeklarációk mondatát a nevükkel.
- Kezdje a sort egy behúzással, hogy kódként előre formázza.
- A „BUG(név)”-vel kezdődő megjegyzések, például „BUG(joe): Ez nem működik”, különlegesek. A Godoc hibákként ismeri fel őket, és jelentést tesz róluk a dokumentáció saját részében.
A Godoc megkönnyítheti a dokumentációval kapcsolatos problémákat
A Godoc használatával hatékonyabb lehet, és kevésbé kell aggódnia a programok kézi dokumentálása miatt.
A dokumentációt pontosnak, részletesnek és lényegre törőnek kell tartania, hogy a célközönség könnyebben olvasható és érthető legyen. Az is létfontosságú, hogy a program módosítása során naprakészen tartsa a kód megjegyzéseit.
Tekintse meg a Godoc csomag dokumentációját, ha többet szeretne megtudni a Godoc használatáról.
