please reconsider ignoring missing doc comments

[bhcleek]

We are in the process of adding support to vim-go for golangci-lint and plan to very soon make it the default to replace gometaliner when running vim-go's :GoMetaLinter.

Please reconsider excluding missing doc comments from golint by default. The README.md justifies the decision with

The rare codebase has such comments

But that rationale is false and goes against Go recommended best practices. Even if the rationale were true, appealing to such a common situation alone is insufficient to justify perpetuating bad practices.

Effective Go specifically states

Every exported (capitalized) name in a program should have a doc comment.

And the only reason we have such great tools as godoc.org is because so many packages implement that guideline.

[pseidemann]

+1
I was wondering why golint is disabled by default. I think this is one of the most important linters which also probably never has false positives

[qustavo]

+1

[qustavo]

I managed to enable it using these parameters:
golangci-lint run --exclude-use-default=false --disable-all --enable=golint

[thaney071]

I managed to enable it using these parameters:
golangci-lint run --exclude-use-default=false --disable-all --enable=golint

that turns back on more than just the doc comment requirements.

It would be nice if this particular one was more configurable.

[matoous]

@jirfag can I get your comment on this? I think @bhcleek made a valid point and if we agree on it I will fix this issue.

[jirfag]

Hi!
In my opinion, 80+% of projects analyzed by golangci-lint have >= 30 identifiers without comments. If we will enable golint warnings it will be annoying for 80% of users. If it's right it doesn't matter what's right or what's not by Go guidelines: this project has the key feature of convenience (no false-positives, easy use, easy and flexible configuration) for users. I really try to maximize the performance and convenience of golangci-lint. Anyone who would like to force comments can disable this default behavior by --exclude-use-default=false.

So, let's talk about numbers. If you are really interested in changing the default behavior please help with calculating the following metrics:

1. share of projects with --exclude-use-default=false
2. share of projects with >=30/>=50/>=100/==0 identifiers without comments

[lopezator]

Even if we ever consider doing this, IMHO this is a "breaking" change, so I would delay it to 2.0.

[matoous]

Or maybe we could postpone this issue until we have (if we have...) warning level severity and report these errors as warnings.

[bhcleek]

If we will enable golint warnings it will be annoying for 80% of users.

Where'd 80% of users come from? Given share of projects with >=30/>=50/>=100/==0 identifiers without comments, it seems that 80% may not be reflective of any hard data.

If it's right it doesn't matter what's right or what's not by Go guidelines: this project has the key feature of convenience (no false-positives, easy use, easy and flexible configuration) for users. I really try to maximize the performance and convenience of golangci-lint.

By that rationale one could never introduce a new linter to golangci-lint that identifies common problems, nor could any additional checks introduced by updating an existing linter be enabled by default.

[ernado]

I think that we can make it opt-in, no breaking changes are needed. Disabling all defaults is pretty annoying, seems like we can be more granular in such things, like govet analyzers settings or exclude-rules :)

I want that feature too and will take a look what we can do (of course without breaking changes and enabling it by default until v2).

[bmhatfield]

I'd like to ++ being able to opt in to godoc enforcement without also re-enabling other pragmatic exclusion rules. Even though we may be in the long tail of projects that will hold themselves to writing docstrings for everything, it's still something we'd like to do.