add comments

Signed-off-by: dongjiang <[email protected]>

Author: dongjiang1989

.golangci.yml

@@ -60,6 +60,7 @@ linters:
       no-unaliased: true
     revive:
       rules:
+        # The following rules are recommended https://github.com/mgechev/revive#recommended-configuration
         - name: blank-imports
         - name: context-as-argument
         - name: context-keys-type
@@ -81,6 +82,9 @@ linters:
         - name: superfluous-else
         - name: unreachable-code
         - name: redefines-builtin-id
+        #
+        # Rules in addition to the recommended configuration above.
+        #
         - name: bool-literal-in-expr
         - name: constant-logical-expr
   exclusions:
@@ -98,9 +102,13 @@ linters:
       - linters:
           - staticcheck
         text: 'SA1019: .*The component config package has been deprecated and will be removed in a future release.'
+      # With Go 1.16, the new embed directive can be used with an un-named import,
+      # revive (previously, golint) only allows these to be imported in a main.go, which wouldn't work for us.
+      # This directive allows the embed package to be imported with an underscore everywhere.
       - linters:
           - revive
         source: _ "embed"
+      # Exclude some packages or code to require comments, for example test code, or fake clients.
       - linters:
           - revive
         text: exported (method|function|type|const) (.+) should have comment or be unexported
@@ -109,21 +117,28 @@ linters:
           - revive
         path: fake_\.go
         text: exported (method|function|type|const) (.+) should have comment or be unexported
+      # Disable unparam "always receives" which might not be really
+      # useful when building libraries.
       - linters:
           - unparam
         text: always receives
+      # Dot imports for gomega and ginkgo are allowed
+      # within test files.
       - path: _test\.go
         text: should not use dot imports
       - path: _test\.go
         text: cyclomatic complexity
       - path: _test\.go
         text: 'G107: Potential HTTP request made with variable url'
+      # Append should be able to assign to a different var/slice.
       - linters:
           - gocritic
         text: 'appendAssign: append result not assigned to the same slice'
       - linters:
           - gocritic
         text: 'singleCaseSwitch: should rewrite switch statement to if statement'
+      # It considers all file access to a filename that comes from a variable problematic,
+      # which is naiv at best.
       - linters:
           - gosec
         text: 'G304: Potential file inclusion via variable'
@@ -135,7 +150,12 @@ linters:
         path: .*/internal/.*
       - linters:
           - unused
+        # Seems to incorrectly trigger on the two implementations that are only
+        # used through an interface and not directly..?
+        # Likely same issue as https://github.com/dominikh/go-tools/issues/1616
         path: pkg/controller/priorityqueue/metrics\.go
+      # The following are being worked on to remove their exclusion. This list should be reduced or go away all together over time.
+      # If it is decided they will not be addressed they should be moved above this comment.
       - path: (.+)\.go$
         text: Subprocess launch(ed with variable|ing should be audited)
       - path: (.+)\.go$