golangci-lint to enable comment check for exported functions

golangci-lint is a command line tool which aggregates a list of different go linters to check whether the source code is in correct condition from different aspects. It is built to run during the CI pipeline so that there is no obvious coding issues before compiling and building the program.

It is easy to run it with just below command

$ golangci-lint run -v
INFO [config_reader] Config search paths: [./ /Users /] 
INFO [config_reader] Used config file .golangci.yml 
INFO [lintersdb] Active 10 linters: [deadcode errcheck gosimple govet ineffassign staticcheck structcheck typecheck unused varcheck] 
INFO [loader] Go packages loading at mode 575 (compiled_files|deps|imports|name|exports_file|files|types_sizes) took 1.890509833s 

However it will not enable the linter which checks whether there is correct comment added for exported functions, types and variables by default. Originally this check was done using golint, but now this tool is replaced by revive and it is not enabled by default.

To add the check on not having comment on exported data, one can add some configuration in the .golangci.yml which is the configuration file for golangci-lint command. If this file doesn't exist, can create one at the root directory of the code repository. The configuration to add is actually enabling the revive linter and also include the corresponding rules to check.

# enable revive linter
linters:
  enable:
    - revive

This will enable revive linter in addition to the enabled linters by default.

INFO [lintersdb] Active 11 linters: [deadcode errcheck gosimple govet ineffassign revive staticcheck structcheck typecheck unused varcheck] 

And it will check not only comments but also some other such as var-naming.  If only focusing on comments, this belongs to the exported rule, hence can enable this rule only in the linters-settings configuration.

linters-settings:
  revive:
    rules:
      - name: exported
        arguments:
          - disableStutteringCheck

Once this is added, one may notice that the comments check is not working still. Why would this happen? Below is one code snippet which misses the // Init ... comment.

func Init(ctx context.Context) (context.Context, error) {
	storage.Init()
	initClient(ctx)

	return ctx, nil
}

The golangci-lint command doesn't report this. To know why, can try to run golangci-lint run -help. There is one flag 

  -e, --exclude strings                Exclude issue by regexp
      --exclude-use-default            Use or not use default excludes:

By default, below issues are not used. This is because many users don't care too much about comments and hence it is not enabled by default.

# EXC0012 revive: Annoying issue about not having a comment. The rare codebase has such comments
- exported (.+) should have comment( \(or a comment on this block\))? or be unexported

# EXC0013 revive: Annoying issue about not having a comment. The rare codebase has such comments
- package comment should be of the form "(.+)...

# EXC0014 revive: Annoying issue about not having a comment. The rare codebase has such comments
- comment on exported (.+) should be of the form "(.+)..."

Just include them in .golangci.yml and run the command again.

issues:
  include:
    - EXC0012  # EXC0012 revive: Annoying issue about not having a comment. The rare codebase has such comments
    - EXC0014  # EXC0014 revive: Annoying issue about not having a comment. The rare codebase has such comments

It will now report the comment issue.

INFO fixer took 0s with no stages                 
components/components.go:9:1: exported: exported function Init should have comment or be unexported (revive)
func Init(ctx context.Context) (context.Context, error) {
^
INFO File cache stats: 1 entries of total size 209B 

Once the comment is added, it would not report the issue again

In summary, to enable the comment check on exported data, below is needed in .golangci.yml.

linters:
  enable:
    - revive

linters-settings:
  revive:
    rules:
      - name: exported
        arguments:
          - disableStutteringCheck

issues:
  include:
    - EXC0012  # EXC0012 revive: Annoying issue about not having a comment. The rare codebase has such comments
    - EXC0014  # EXC0014 revive: Annoying issue about not having a comment. The rare codebase has such comments

Hope this helps.