golints: should have comment or be unexported

[aldas]

I switched from golint to staticcheck and noticed that ... should have comment or be unexported is not reported. Not that I am particularly good at documenting (being non-native English speaker it is even harder) but it felt off not being required to document public functions/methods. it is that same feeling that bothers me when me do not write tests - I feel guilty.

So I started to search what would be the reasoning for not having that check and found #542 I do understand that commenting stuff that you never indent to share with other is annoying and most of the time unnecessary but for public libraries/APIs this argument is maybe in somewhat on bar with argumentation why not to write tests. Having optional checks that nudge people in positive direction, to think about and write documentation (for public stuff), would be nice to have.

This is not a demand, in my mind I am trying to argue for that idea and not make demands. Please do not take it in that way. Please consider adding check like that in future.

[dominikh]

The decision not to include that check wasn't based on code one never intents to share. It was based on the fact that not all public API needs to be documented, even in a public, well-documented project. The most obvious examples are the String() string and Error() string methods, which always do the same thing and don't require documentation. The list of things that don't need documentation is infinite and can't be predetermined by us. In golint, this check was a constant source of useless warnings.

Not all things can be enforced well by tools, and I hold the belief that this check is one that should be done by fellow humans during code review.

[aldas]

Is it categorical no or this could be added as contribution and be non-default as ST1000 – Incorrect or missing package commen is? For example - if you switch this on - you commit to comment every public method (no filtering/guessing by the tool).

[dominikh]

I'm afraid it's a categorical no. Actually writing the check is trivial (more so than merging a contribution, really). My concern lies with people who (against my recommendation) enable all checks. These would end up with this new check. Even our optional checks are designed in a way that they aren't noisy, and wouldn't cause "harm" should they be turned on accidentally. I don't think that this check meets either requirement.