Czy źle wykluczyć godocs na wyeksportowanych nazwach?

Question

Według „skuteczna Go” golang.org/doc/effective_go

Każdy eksportowane (kapitalizowane) nazwa w programie powinny mieć komentarz doc.

powiedzmy Mam obsługi widok na prostej aplikacji internetowej

// Handle the front page of the website 
func FrontPageView(w http.ResponseWriter, r *http.Request) { 
    controllers.RenderBasicPage(w, "frontPage") 
} 

Moje pytanie jest takie: czy to godoc naprawdę konieczne? Być może jestem po prostu zakochany w Czystym Kodzie Roberta Martina w tej chwili, ale wygląda na to, że jest to zmienna o naprawdę dużej nazwie, w tym przypadku FrontPageView usuwa potrzebę takiego bóstwa. To prawdopodobnie pochodna/duplikat "są potrzebne javadocs?" lub "czy konieczne są doktryny Pythona?", ale chcę się upewnić, że ucząc się nowego języka, trzymam się kanonicznych sposobów na zrobienie rzeczy specyficznych dla języka.

Answer 1

Zauważ, że golint powie ci, że doc dla FrontPageView() musi zaczynać się

// FrontPageView ... 

I tak, to jest dobra praktyka, aby obejmować (tutaj krótka) komentarz na wszystkich eksportowanych metody, funkcje, jak opisane również w "Go Code Review Comments".

Komentarze dokumentujące deklaracje powinny być pełne zdania, nawet jeśli wydaje się nieco zbędny.
Takie podejście sprawia, że ​​dobrze się formatują po wyodrębnieniu do dokumentacji godoc.

Komentarze powinien zaczynać się od nazwy rzeczy są opisane i koniec w okresie:

// A Request represents a request to run a command. 
type Request struct { ... 

// Encode writes the JSON encoding of req to w. 
func Encode(w io.Writer, req *Request) { ... 

---

to moje zrozumienie, że skutecznie czysty kod oznacza utrzymanie funkcji prostych o nazwie opisuje rolę jednej funkcji;

Następnie dokumentacja może zawierać przypadki brzegowe (nawet jeśli w twoim przypadku nie ma żadnych).
W każdym przypadku dodanie krótkiego dokumentu nie spowoduje, że będzie "mniej czysty".

ponieważ stają się bardziej złożone, dzieli się je na wiele równie prostych funkcji.

Używam gocyclo do tego: dowolny cyclomatic complexity powyżej 10, i dzielę tę funkcję.

Również zmiany będą wymagać aktualizacji w godoc jak również nazwę

czyli pomysł: zachować dokument w synchronizacji (i golint pomaga)

Answer 2

Oto kilka powodów do napisania komentarzy do dokumentu:

• Lint. Jeśli użyjesz golint, wydrukuje ostrzeżenia o każdej wyeksportowanej metodzie, która nie ma komentarza do dokumentu. Jeśli masz dużo osób, możesz przypadkowo przegapić coś, co powinno być udokumentowane. Posiadanie w kodzie zero ostrzeżeń o wartości golint pozwala szybko reagować, gdy gdzieś brakuje dokumentów lub masz inne niespójności w stylu.

• Zmiany. Kod zmienia się cały czas. Może teraz twój FrontPageView jest jednolinijkowy bez zawartości, ale w przyszłości może stać się bardziej skomplikowany, więc i tak musisz dodać komentarz do dokumentu, aby wyjaśnić, co się dzieje.

• Grep. W twoim przykładzie, jeśli jestem nowym programistą i mam zadanie związane z pierwszą stroną, prawdopodobnie wykonam godoc pkg | grep 'front page' lub git grep 'front page'. Jeśli nie dostarczysz komentarza doktora, oba te będą prawdopodobnie dla mnie bezużyteczne, i będę musiał albo uruchomić interfejs webowy godoc, żeby szukać go moimi oczami, albo spróbować kilku innych grepów.