"Exported type should have comment or be unexported" golang VS Code
Solution 1
Just add a comment above it, starting with the name of your type (or function, method etc.) like this:
// Agent is ...
type Agent struct {
name string
categoryId int
}
This linter error is caused by your Agent
type being exported, even if its attributes are not. To not export your type, define it in lowercase like such:
type agent struct {
name string
categoryId int
}
The reason why your linter complains about this is that godoc uses those comments to automatically generate documentation for your projects. You can find many examples of such documented Go projects at pkg.go.dev.
If you upload one of your Go projects to GitHub for example, pkg.go.dev will automatically generate a documentation for you using those comments. You can even add runnable code examples and many other things, as shown on go-doc tricks.
Solution 2
Who
This warning is produced by the official linter for Go source code - golint. Golint is used as the default linter by the Go extension in Visual Studio Code editor.
Why
To understand the reason why golint showed that warning, we can refer to the "Commentary" section in the "Effective Go" (the official document that gives tips for writing clear, idiomatic Go code). Here is the related quote:
Every exported (capitalized) name in a program should have a doc comment.
But this indeed can be annoying if you tend to write self-documenting code (i.e. the intention is clear from a name itself etc).
Solution
Besides the already proposed solutions, what you can do is start using the alternative and more advanced golangci-lint which is a Go linters aggregator. It has golint disabled by default, so this annoying warning about missing doc comments will not be triggered. Of course you can turn this warning on if you want by using the related flags (see --exclude strings
and --exclude-use-default
).
The possibility to change the linter is also mentioned on the description page of Go extension:
How to change lint tool for the Go Extension in VS Code
In order to change lint tool in VS Code perform the following steps.
1) Choose the "Configure Extension Settings" in the Go Extension's management menu:
2) Select "golangci-lint" from the related drop-down list:
3) To prevent VS Code from freezing as a result of using this powerful linter, add the --fast
flag as described in the "Editor Integration" instructions.
To do that, you need to navigate to the Go Extension configuration page (as in step 1), open the settings.json
file and add the related configuration as shown on the below screenshots:
NB! Here is a quote from the "golangci-lint" FAQ:
Why running with --fast is slow on the first run?
Because the first run caches type information. All subsequent runs will be fast. Usually this options is used during development on local machine and compilation was already performed.
channa ly
Former Senior Software Engineer @instedd, @sureswiftcapital. Co-Founder @bookmebus. Tech Lead @vtenh #rails #aws #api #docker #postgresql #elasticsearch #js I design, develop, and deploy applications in rails to AWS and App Store. Linkedin | Medium | Github
Updated on July 09, 2022Comments
-
channa ly almost 2 years
I tried this code in Go:
type Agent struct { name string // Not exported categoryId int // Not exported }
And VS Code reports the following problem:
exported type Agent should have comment or be unexported
The warning is kind of annoying. So I have the following questions:- How to get rid of it?
- What comment should I put?
- Is there any default comment template for this?
It asks me to put a comment but it does not offer me to add one by default.
-
Volker over 5 yearsAdd a comment or do not run golint.
-
channa ly over 5 yearsit can be anything? free text?
-
Ullaakut over 5 yearsIt has to start with your type name, like in my example.
-
Ullaakut over 5 yearsThat's the only limitation
-
Thiago Valentim over 4 yearsAfter some time programming in Go this type of thing turns more natural... To be more about it, go to the "Effective Go" in the documentation, in resume, the idea is to be more clear and write idiomatic Go code. Thanks for sharing the tips
-
dfarrell07 almost 4 yearsGolangci-lint is a wrapper of multiple linters. What you're doing here is disabling it running golint entirely.
-
informatik01 almost 4 years@dfarrell07 Yes, golangci-lint is a Go linters aggregator. So what's the problem? "Disabling it running golint entirely" - what do you mean, for the case when a lack of comments should be reported? It solves the problem in question, the one the OP were asking - so how is it wrong, when even Microsoft developers (the authors of the VS Code Go extension) also directly mention it. What's your problem? Those
--exclude
and--exclude-use-default
flags ARE MEANT just for such cases, to make developers' lives easier. -
informatik01 almost 4 yearsI will update my answer to mention that golang-ci is a Go linters aggregator to make it more formal.
-
dfarrell07 almost 4 yearsYou say "It has the default settings not to warn about those missing doc comments", and I'm saying that's missleading. It doesn't ignore them, it just doesn't run golint.
-
informatik01 almost 4 years@dfarrell07 If specifying how exactly golangci achieves this not reporting the missing doc comments issue - then you're right. I will update my answer accordingly to mention this moment. Thanks for pointing this out.
-
dfarrell07 almost 4 yearsClarification that Golint stops being run, not just warning disabled, is my key issue. That's clear in your latest version. Thanks!
-
informatik01 over 2 years@Ullaakut Seems like it doesn't "have to" start with the type name, but IF it does - it may be useful. Here is a quote from the documentation: "If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep." And then it gives an example of how it may be useful etc. So it's not a restriction, but rather a useful option.