Kiedy myślisz o programowaniu, naturalne jest skupienie się na tematach takich jak języki, algorytmy i debugowanie. Ale dokumentacja techniczna może być równie ważna, aby uzyskać prawidłową.

Bez dobrej dokumentacji może ucierpieć możliwość ponownego wykorzystania kodu. Użytkownicy nowi w kodzie mogą łatwo się zgubić lub sfrustrować, jeśli dokumentacja nie jest odpowiednia. Ważne jest nie tylko zrozumienie, co robi program, ale także jak — a nawet dlaczego — to robi.

Pakiety takie jak Pydoc for Python i Javadoc for Java pomagają automatyzować część procesu. Narzędzie Godoc robi to samo dla Go.

Co to jest Godoc?

Godoc to pakiet Go, który pozwala tworzyć, zarządzać i korzystać z dokumentacji Go w „sposobie Go”. Droga Go to zbiór zasad, których jako programista Go powinieneś przestrzegać, aby poprawić jakość kodu.

Korzystając z Godoc, możesz łatwo czytać dokumentację i kod innych programistów. Możesz także zautomatyzować tworzenie własnej dokumentacji i publikować ją za pomocą Godoc.

Godoc jest podobny do

instagram viewer
Javadoc, dokumentator kodu dla Java. Obaj używają komentarzy i kodu w modułach do generowania dokumentacji. Oba narzędzia tworzą strukturę dokumentacji w formacie HTML, dzięki czemu można ją przeglądać w przeglądarce.

Pierwsze kroki z Godoc

Korzystanie z Godoc jest łatwe. Aby rozpocząć, zainstaluj pakiet Godoc ze strony golang za pomocą tego polecenia:

iść pobierz golang.org/x/tools/cmd/godoc

Uruchomienie tego polecenia spowoduje zainstalowanie Godoc w określonym obszarze roboczym. Po zakończeniu powinieneś być w stanie uruchomić godoc polecenie w terminalu. Jeśli w instalacji występują błędy, spróbuj zaktualizować Go do najnowszej wersji.

Godoc szuka komentarzy jedno- i wielowierszowych do dołączenia do generowanej dokumentacji.

Pamiętaj, aby sformatować kod w sposób Go, jak wyjaśniono w publikacja Effective Go przez zespół Go dla najlepszych wyników.

Oto przykład użycia jednowierszowych komentarzy w stylu C++:

// Użytkownik jest modelem struktury zawierającym
rodzaj Użytkownik struktura {
}

Możesz także użyć komentarzy blokowych w stylu C:

/* 
Użytkownik to niestandardowa struktura danych
Możesz tu dołączyć dowolny tekst, a serwer Godoc sformatuje go po uruchomieniu.
*/
rodzaj Użytkownik struktura {
}

W powyższych komentarzach „User” rozpoczyna zdania, ponieważ komentarz opisuje, co robi struktura User. To jeden z wielu tematów poruszanych przez Go way. Rozpoczęcie zdań dokumentacji przy użyciu użytecznej nazwy jest kluczowe, ponieważ pierwsze zdanie pojawia się na liście pakietów.

Uruchamianie serwera Godoc

Po skomentowaniu kodu możesz uruchomić godoc polecenie w terminalu, z katalogu kodu projektu.

Tradycyjnie programiści Go używają portu 6060 do przechowywania dokumentacji. To jest polecenie do uruchomienia serwera Godoc na tym porcie:

godoc - http=:6060

Powyższe polecenie przechowuje dokumentację Twojego kodu na host lokalny lub 127.0.0.1. Port nie musi mieć 6060; godoc będzie działać na każdym niezajętym porcie. Jednak zawsze najlepiej jest przestrzegać konwencji dokumentacji Go.

Po uruchomieniu polecenia możesz wyświetlić dokumentację w przeglądarce, odwiedzając Lokalny Gospodarz: 6060. Czas potrzebny na wygenerowanie dokumentacji przez Godoc będzie zależał od jej rozmiaru i złożoności.

Poniższy kod jest zgodny ze sposobem Go, w tym przypadku za pomocą komentarzy jednowierszowych.

// nazwa pakietu
pakiet użytkownik
// fmt odpowiada za formatowanie
import (
 „fmt”
)


// Użytkownik jest strukturą ludzkich danych
rodzaj Użytkownik struktura {
 Wiek int
 Nazwa strunowy
}


funkcjonowaćGłówny() {
// człowiek to inicjalizacja struktury User
 człowiek := Użytkownik {
 Wiek: 0,
 Imię: "osoba",
 }


fmt. Println (człowiek. Rozmowa())
}
// Talk to metoda struktury User
funkcjonować(Użytkownik odbiornika)Rozmowa()strunowy {
zwrócić „Każdy użytkownik może coś powiedzieć!”
}

Jeśli uruchomisz Godoc na powyższym module kodu, powinieneś zobaczyć dane wyjściowe wyglądające mniej więcej tak:

Zauważ, że jest w znanym formacie, podobnym do tego, który znajdziesz na oficjalnej stronie dokumentacji Go.

Godoc używa komentarza poprzedzającego deklarację pakietu jako Przegląd. Upewnij się, że ten komentarz opisuje, co robi Twój program.

The Indeks zawiera łącza do deklaracji typów i metod, dzięki czemu można szybko do nich przejść.

Godoc zapewnia również funkcjonalność przeglądania kodu źródłowego, z którego składa się pakiet w Pliki pakietów Sekcja.

Ulepszanie dokumentacji za pomocą Godoc

W dokumentacji Godoc możesz zawrzeć więcej niż zwykły tekst. Możesz dodać adresy URL, do których Godoc będzie generować linki i uporządkować komentarze w akapity.

Jeśli chcesz umieścić link do zasobu, wpisz adres URL w swoim komentarzu, a Godoc rozpozna go i doda link. W przypadku akapitów zostaw pustą linię komentarza.

// Pakiet główny
pakiet Główny
// Dokument reprezentuje zwykły dokument.
//
// Łączyć z https://google.com
rodzaj Dokument struktura {
 strony int
 Bibliografia strunowy
 podpisany głupota
}


// Write zapisuje nowy dokument w magazynie
//
// Możesz dowiedzieć się o pisaniu z Wikipedia.com
funkcjonowaćPisać() {
}

Pamiętaj, że Godoc wymaga podania pełnych adresów URL, aby mógł je połączyć. W tym przykładzie adres URL Google zawiera https:// prefiks, więc Godoc dodaje do niego link. Ponieważ domena Wikipedii sama w sobie nie jest pełnym adresem URL, Godoc zostawi ją w spokoju.

Oto kilka najlepszych zasad, które należy stosować podczas dokumentowania kodu Go:

  • Dokumentacja powinna być prosta i zwięzła.
  • Rozpocznij zdanie funkcji, typów i deklaracji zmiennych od ich nazw.
  • Zacznij wiersz od wcięcia, aby wstępnie sformatować go jako kod.
  • Komentarze zaczynające się od „BUG(name)”, takie jak „BUG(joe): To nie działa”, są wyjątkowe. Godoc rozpozna je jako błędy i zgłosi je we własnej sekcji dokumentacji.

Godoc może złagodzić problemy związane z dokumentacją

Korzystając z Godoc, możesz być bardziej produktywny i mniej martwić się o wysiłek związany z ręcznym dokumentowaniem swoich programów.

Powinieneś utrzymywać swoją dokumentację dokładną, szczegółową i na temat, aby ułatwić odbiorcom docelowym czytanie i zrozumienie. Ważne jest również, aby komentarze do kodu były aktualne podczas modyfikowania programu.

Zapoznaj się z dokumentacją pakietu Godoc, aby dowiedzieć się więcej o korzystaniu z Godoc.