Is it bad form to exclude godocs on exported names?

Question

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.

Answer 1

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)

Answer 2

Here is a couple of reasons to write doc comments:

• Lint. If you use golint, it will print warnings on every exported method that has no doc comment. If you have a lot of those you can accidentally miss something that should actually be documented. Having zero golint warnings in your code allows you to react quickly when the docs are missing somewhere or you have other style inconsistencies.

• Changes. The code changes all the time. Maybe now your FrontPageView is a one-liner with no content, but in the future it might become more complex, so you'll have to add a doc comment anyway to explain, what's going on.

• Grep. In your example, if I am a new developer and I'm given a task having to do with the front page, I will probably do godoc pkg | grep 'front page' or git grep 'front page'. If you don't provide a doc comment, both of those will probably be useless for me, and I'll have to either launch the godoc web interface to look for it with my eyes, or try a few other greps.