När du tänker på programmering är det naturligt att fokusera på ämnen som språk, algoritmer och felsökning. Men teknisk dokumentation kan vara lika viktig att få rätt.
Utan bra dokumentation kan kodåteranvändbarhet bli lidande. Användare som är nya i en kodbas kan lätt gå vilse eller frustrerade om dokumentationen inte är på noll. Det är inte bara viktigt att förstå vad ett program gör, utan även hur – eller till och med varför – det gör det.
Paket som Pydoc för Python och Javadoc för Java hjälper till att automatisera en del av processen. Godoc-verktyget gör precis samma sak för Go.
Vad är Godoc?
Godoc är ett Go-paket som låter dig skapa, hantera och använda Go-dokumentation på "the Go way". Go-vägen är en uppsättning principer som du som Go-programmerare bör följa för att förbättra kodkvaliteten.
Med Godoc kan du enkelt läsa andra utvecklares dokumentation och kod. Du kan också automatisera skapandet av din egen dokumentation och publicera den med Godoc.
Godoc liknar Javadoc, koddokumentatorn för Java
. De använder båda kommentarer och kod i moduler för att generera dokumentation. Och båda verktygen strukturerar den dokumentationen i HTML så att du kan se den i en webbläsare.Komma igång med Godoc
Att använda Godoc är enkelt. För att börja, installera Godoc-paketet från golang-webbplatsen med detta kommando:
gå hämta golang.org/x/tools/cmd/godoc
Om du kör det här kommandot installeras Godoc i din angivna arbetsyta. När den är klar bör du kunna köra godoc kommando i en terminal. Om det finns några fel med din installation, försök att uppdatera Go till en senaste version.
Godoc letar efter kommentarer på en och flera rader som ska inkluderas i dokumentationen som den genererar.
Se till att formatera kod på Go-vägen, som förklaras i Effektiv Go-publikationen av Go-teamet för bästa resultat.
Här är ett exempel med en rad kommentarer i C++-stil:
// User är en strukturmodell som innehåller
typ Användare struktur {
}
Du kan också använda blockkommentarer i C-stil:
/*
Användare är en anpassad datastrukturDu kan inkludera vilken text som helst här och Godoc-servern kommer att formatera den när du kör den.
*/
typ Användare struktur {
}
I kommentarerna ovan börjar "Användare" meningarna eftersom kommentaren beskriver vad användarstrukturen gör. Detta är ett av många ämnen som Go-vägen diskuterar. Att starta dokumentationsmeningar med ett användbart namn är avgörande eftersom den första meningen visas i paketlistan.
Köra en Godoc-server
När du har kommenterat din kod kan du köra godoc kommandot i din terminal, från ditt projekts kodkatalog.
Konventionellt använder Go-utvecklare port 6060 att vara värd för dokumentation. Detta är kommandot för att köra en Godoc-server på den porten:
godoc -http=:6060
Kommandot ovan är värd för din koddokumentation localhost, eller 127.0.0.1. Porten behöver inte vara 6060; godoc kommer att köras på alla lediga hamnar. Det är dock alltid bäst att följa Go-dokumentationskonventionerna.
När du har kört kommandot kan du se din dokumentation i en webbläsare genom att besöka lokal värd: 6060. Den tid det tar för Godoc att generera din dokumentation beror på dess storlek och komplexitet.
Koden nedan följer Go-vägen, i det här fallet med kommentarer på en rad.
// paketets namn
paket användare// fmt ansvarar för formateringen
importera (
"fmt"
)// Användaren är en struktur av mänskliga data
typ Användare struktur {
Ålder int
namn sträng
}funchuvud() {
// human är en initiering av användarstrukturen
människa := Användare {
Ålder: 0,
Namn: "person",
}fmt. Println (människ. Prata())
}
// Talk är en metod för användarstrukturen
func(mottagare användare)Prata()sträng {
lämna tillbaka "Varje användare får säga något!"
}
Om du kör Godoc på kodmodulen ovan bör du se utdata som ser ut ungefär så här:
Lägg märke till att det är i ett välbekant format, liknande det du hittar på Gos officiella dokumentationswebbplats.
Godoc använder kommentaren som föregår paketdeklarationen som Översikt. Se till att den här kommentaren beskriver vad ditt program gör.
De Index innehåller länkar till typdeklarationerna och metoderna så att du snabbt kan navigera till dem.
Godoc tillhandahåller också funktionalitet för att visa källkoden som utgör paketet i Paketera filer sektion.
Förbättra din dokumentation med Godoc
Du kan inkludera mer än bara vanlig text i din Godoc-dokumentation. Du kan lägga till webbadresser som Godoc genererar länkar till och strukturera dina kommentarer i stycken.
Om du vill länka till en resurs, skriv URL: en i din kommentar, så kommer Godoc att känna igen den och lägga till en länk. Lämna en tom kommentarsrad för stycken.
// Paket huvud
paket huvud// Dokument representerar ett vanligt dokument.
//
// Länk till https://google.com
typ Dokumentera struktur {
sidor int
referenser sträng
signerad bool
}// Write skriver ett nytt dokument till lagringen
//
// Du kan lära dig om att skriva från Wikipedia.com
funcSkriva() {
}
Observera att Godoc kräver att du skriver ut webbadresser i sin helhet för att den ska länka dem. I det här exemplet innehåller Google URL: en https:// prefix, så Godoc lägger till en länk till det. Eftersom Wikipedia-domänen inte är en fullständig URL ensam, kommer Godoc att lämna den ifred.
Här är några bästa principer att tillämpa när du dokumenterar din Go-kod:
- Håll din dokumentation enkel och koncis.
- Börja meningen med funktioner, typer och variabeldeklarationer med deras namn.
- Börja en rad med ett indrag för att förformatera den som kod.
- Kommentarer som börjar "BUG(namn)" som "BUG(joe): Det här fungerar inte" är speciella. Godoc kommer att känna igen dem som buggar och rapportera dem i sin egen del av dokumentationen.
Godoc kan lindra din dokumentationsproblem
Genom att använda Godoc kan du vara mer produktiv och oroa dig mindre för ansträngningen att dokumentera dina program för hand.
Du bör hålla din dokumentation exakt, detaljerad och till punkt för att göra det lättare för din målgrupp att läsa och förstå. Det är också viktigt att du håller kodkommentarer uppdaterade när du ändrar ditt program.
Kolla in Godoc-paketets dokumentation för att lära dig mer om hur du använder Godoc.