From c3e89db0df4808bff0378fc5cd23ac1082be9be9 Mon Sep 17 00:00:00 2001
From: ashmrtn <3891298+ashmrtn@users.noreply.github.com>
Date: Mon, 29 Aug 2022 15:46:57 -0700
Subject: [PATCH] Lint doc for wsl (#678)

Some tips and examples on coexisting with the wsl linter
---
 docs/docs/developers/linters.md | 115 ++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)

diff --git a/docs/docs/developers/linters.md b/docs/docs/developers/linters.md
index d0b0896d8..09d8a5798 100644
--- a/docs/docs/developers/linters.md
+++ b/docs/docs/developers/linters.md
@@ -62,6 +62,121 @@ the linter/rule that triggered the message. This ensures the lint error is only
 ignored for that linter. Combining the linter/rule with the error message text
 specific to that error also helps minimize collisions with other lint errors.
 
+## Working with the linters
+
+Some of the enabled linters, like `wsl`, are picky about how code is arranged.
+This section provides some tips on how to organize code to reduce lint errors.
+
+### `wsl`
+`wsl` is a linter that requires blank lines in parts of the code. It helps make
+the codebase more uniform and ensures the code doesn't feel too compact.
+
+#### Short-assignments versus var declarations
+Go allows declaring and assigning to a variable with either short-assignments
+(`x := 42`) or var assignments (`var x = 42`). `wsl` doesn't allow
+grouping these two types of variable declarations together. To work around this,
+you can convert all your declarations to one type or the other. Converting to
+short-assignments only works if the types in question have accessible and
+suitable default values.
+
+For example, the mixed set of declarations and assignments:
+
+```go
+var err error
+x := 42
+```
+
+should be changed to the following because using a short-assignment for type
+`error` is cumbersome.
+
+```go
+var (
+    err error
+    x = 42
+)
+```
+
+#### Post-increment and assignments
+`wsl` doesn't allow statements before an assignment without a blank line
+separating the two. Post-increment operators (e.x. `x++`) count as statements
+instead of assignments and may cause `wsl` to report an error. You can avoid
+this by moving the post-increment operator to be after the assignment instead of
+before it if the assignment doesn't depend on the increment operation.
+
+For example, the snippet:
+
+```go
+x++
+found = true
+```
+
+should be converted to:
+
+```go
+found = true
+x++
+```
+
+#### Functions using recently assigned values
+`wsl` allows functions immediately after assignments, but only if the function
+uses the assigned value. This requires an ordering for assignments and
+function calls.
+
+For example, the following code
+
+```go
+a := 7
+b := 42
+foo(a)
+```
+
+should be changed to
+
+```go
+b := 42
+a := 7
+foo(a)
+```
+
+If both the second assignment and function call depend on the value of the first
+assignment then the assignments and function call must be separated by a blank
+line.
+
+```go
+a := 7
+b := a + 35
+
+foo(a, b)
+```
+
+#### Function calls and checking returned error values
+One of the other linters expects error checks to follow assignments to the error
+variable without blank lines separating the two. One the other hand, `wsl` has
+requirements about what statements can be mixed with assignments. To work
+around this, you should separate assignments that involve an error from other
+assignments. For example
+
+```go
+a := 7
+b := 42
+c, err := foo()
+if err != nil {
+  ...
+}
+```
+
+should be changed to
+
+```go
+a := 7
+b := 42
+
+c, err := foo()
+if err != nil {
+  ...
+}
+```
+
 ## Common problem linters
 
 Some linter messages aren't clear about what the issue is. Here's common