Is it a bad form to exclude godocs on exported names?

Question

According to "Effective Go" golang.org/doc/effective_go

Each exported (title) name in the program must have a comment on the document.

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, is this very important? Maybe I'm just in love with Robert Martin Clean Code right now, but it seems to be an efficiently named variable, in which case FrontPageView eliminates the need for such a godoc. This is probably a derivative / duplicate of "Do I need javadocs?" or "do I need python docstrings?", but I want to make sure that while learning a new language, I adhere to the canonical behaviors associated with the language.

Answer 1

Note that golint will tell you that the document for FrontPageView () should start with

 // FrontPageView ... 

And yes, it’s good practice to include a (short) commentary on all exported methods, functions, as also described in the Go Code Review Comments .

Comments documenting ads should be complete sentences , even if this seems a bit redundant .
This approach allows them to be formatted well when extracted into godoc documentation.

Comments should begin with the name of the thing being described and end over the 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) { ... 

---

I understand that effective clean code means saving simple functions with a name that describes a function one role;

Then the document may include edge cases (even if they are not in your case).
In any case, adding a short document will not make it “less clean”.

as they become more complex, you break them down into several equally simple functions.

I use gocyclo for this: the cyclomatic complexity is above 10, and I split the function.

In addition, changes require an update to godoc as well as a name

This is the idea: synchronizing a document (and golint helps)

Answer 2

Here are a few reasons to write doc comments:

• Lint

  . If you use golint , it will print warnings for each exported method that has no comments on the document. If you have a lot of those, you might accidentally skip something that needs to be documented. With zero golint warnings in your code, you can react quickly when documents are missing somewhere or you have other style inconsistencies.

• Change. The code changes all the time. Your FrontPageView may now be single-line without content, but it may become more complex in the future, so you will have to add a comment to the document anyway to explain what is going on.

• Grep. In your example, if I am a new developer and I have been given a task related to the first page, I will probably do godoc pkg | grep 'front page' godoc pkg | grep 'front page' or git grep 'front page' . If you do not provide a comment on the dock tag, both of these functions are likely to be useless to me, and I will either have to run the godoc web interface to look for it with my own eyes, or try a few other greps.