According to "Effective Go" golang.org/doc/effective_go
Every exported (capitalized) name in a program should have a doc comment.
Let's say I have a view handler on a simple web application
// Handle the front page of the website
func FrontPageView(w http.ResponseWriter, r *http.Request) {
controllers.RenderBasicPage(w, "frontPage")
}
My question is this: is that godoc really necessary? Perhaps I'm just in love with Robert Martin's Clean Code right now, but it seems an effectively named variable, in this case FrontPageView removes the need for such a godoc. This is probably a derivative/duplicate of "are javadocs necessary?" or "are python docstrings necessary?", but I do want to make sure that when learning a new language I'm sticking to the language-specific canonical ways-to-do-things.
Note that golint would tell you that the doc for FrontPageView() must start with
// FrontPageView ...
And yes, it is good practice to include (here a short) comment on all exported methods, functions, as described also in "Go Code Review Comments".
Comments documenting declarations should be full sentences, even if that seems a little redundant.
This approach makes them format well when extracted into godoc documentation.Comments should begin with the name of the thing being described and end in a period:
// 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) { ...
it's my understanding that effectively clean code means keeping functions simple with a name that describes the function's one role;
Then the doc can include edge cases (even if in your case there are none).
In any case, adding a short doc won't make it "less clean".
as they get more complex you split them into multiple, equally simple, functions.
I use gocyclo for this: any cyclomatic complexity above 10, and I split the function.
Also, changes would require an update in the godoc as well as the name
That is the idea: keeping the doc in sync (and golint helps)