1package stylecheck 2 3import "honnef.co/go/tools/analysis/lint" 4 5var Docs = lint.Markdownify(map[string]*lint.Documentation{ 6 "ST1000": { 7 Title: `Incorrect or missing package comment`, 8 Text: `Packages must have a package comment that is formatted according to 9the guidelines laid out in 10https://github.com/golang/go/wiki/CodeReviewComments#package-comments.`, 11 Since: "2019.1", 12 NonDefault: true, 13 }, 14 15 "ST1001": { 16 Title: `Dot imports are discouraged`, 17 Text: `Dot imports that aren't in external test packages are discouraged. 18 19The \'dot_import_whitelist\' option can be used to whitelist certain 20imports. 21 22Quoting Go Code Review Comments: 23 24> The import . form can be useful in tests that, due to circular 25> dependencies, cannot be made part of the package being tested: 26> 27> package foo_test 28> 29> import ( 30> "bar/testutil" // also imports "foo" 31> . "foo" 32> ) 33> 34> In this case, the test file cannot be in package foo because it 35> uses bar/testutil, which imports foo. So we use the 'import .' 36> form to let the file pretend to be part of package foo even though 37> it is not. Except for this one case, do not use import . in your 38> programs. It makes the programs much harder to read because it is 39> unclear whether a name like Quux is a top-level identifier in the 40> current package or in an imported package.`, 41 Since: "2019.1", 42 Options: []string{"dot_import_whitelist"}, 43 }, 44 45 "ST1003": { 46 Title: `Poorly chosen identifier`, 47 Text: `Identifiers, such as variable and package names, follow certain rules. 48 49See the following links for details: 50 51- https://golang.org/doc/effective_go.html#package-names 52- https://golang.org/doc/effective_go.html#mixed-caps 53- https://github.com/golang/go/wiki/CodeReviewComments#initialisms 54- https://github.com/golang/go/wiki/CodeReviewComments#variable-names`, 55 Since: "2019.1", 56 NonDefault: true, 57 Options: []string{"initialisms"}, 58 }, 59 60 "ST1005": { 61 Title: `Incorrectly formatted error string`, 62 Text: `Error strings follow a set of guidelines to ensure uniformity and good 63composability. 64 65Quoting Go Code Review Comments: 66 67> Error strings should not be capitalized (unless beginning with 68> proper nouns or acronyms) or end with punctuation, since they are 69> usually printed following other context. That is, use 70> fmt.Errorf("something bad") not fmt.Errorf("Something bad"), so 71> that log.Printf("Reading %s: %v", filename, err) formats without a 72> spurious capital letter mid-message.`, 73 Since: "2019.1", 74 }, 75 76 "ST1006": { 77 Title: `Poorly chosen receiver name`, 78 Text: `Quoting Go Code Review Comments: 79 80> The name of a method's receiver should be a reflection of its 81> identity; often a one or two letter abbreviation of its type 82> suffices (such as "c" or "cl" for "Client"). Don't use generic 83> names such as "me", "this" or "self", identifiers typical of 84> object-oriented languages that place more emphasis on methods as 85> opposed to functions. The name need not be as descriptive as that 86> of a method argument, as its role is obvious and serves no 87> documentary purpose. It can be very short as it will appear on 88> almost every line of every method of the type; familiarity admits 89> brevity. Be consistent, too: if you call the receiver "c" in one 90> method, don't call it "cl" in another.`, 91 Since: "2019.1", 92 }, 93 94 "ST1008": { 95 Title: `A function's error value should be its last return value`, 96 Text: `A function's error value should be its last return value.`, 97 Since: `2019.1`, 98 }, 99 100 "ST1011": { 101 Title: "Poorly chosen name for variable of type `time.Duration`", 102 Text: `\'time.Duration\' values represent an amount of time, which is represented 103as a count of nanoseconds. An expression like \'5 * time.Microsecond\' 104yields the value \'5000\'. It is therefore not appropriate to suffix a 105variable of type \'time.Duration\' with any time unit, such as \'Msec or 106Milli\'.`, 107 Since: `2019.1`, 108 }, 109 110 "ST1012": { 111 Title: `Poorly chosen name for error variable`, 112 Text: `Error variables that are part of an API should be called \'errFoo\' or 113\'ErrFoo\'.`, 114 Since: "2019.1", 115 }, 116 117 "ST1013": { 118 Title: `Should use constants for HTTP error codes, not magic numbers`, 119 Text: `HTTP has a tremendous number of status codes. While some of those are 120well known (200, 400, 404, 500), most of them are not. The \'net/http\' 121package provides constants for all status codes that are part of the 122various specifications. It is recommended to use these constants 123instead of hard-coding magic numbers, to vastly improve the 124readability of your code.`, 125 Since: "2019.1", 126 Options: []string{"http_status_code_whitelist"}, 127 }, 128 129 "ST1015": { 130 Title: `A switch's default case should be the first or last case`, 131 Since: "2019.1", 132 }, 133 134 "ST1016": { 135 Title: `Use consistent method receiver names`, 136 Since: "2019.1", 137 NonDefault: true, 138 }, 139 140 "ST1017": { 141 Title: `Don't use Yoda conditions`, 142 Text: `Yoda conditions are conditions of the kind \'if 42 == x\', where the 143literal is on the left side of the comparison. These are a common 144idiom in languages in which assignment is an expression, to avoid bugs 145of the kind \'if (x = 42)\'. In Go, which doesn't allow for this kind of 146bug, we prefer the more idiomatic \'if x == 42\'.`, 147 Since: "2019.2", 148 }, 149 150 "ST1018": { 151 Title: `Avoid zero-width and control characters in string literals`, 152 Since: "2019.2", 153 }, 154 155 "ST1019": { 156 Title: `Importing the same package multiple times`, 157 Text: `Go allows importing the same package multiple times, as long as 158different import aliases are being used. That is, the following 159bit of code is valid: 160 161 import ( 162 "fmt" 163 fumpt "fmt" 164 format "fmt" 165 _ "fmt" 166 ) 167 168However, this is very rarely done on purpose. Usually, it is a 169sign of code that got refactored, accidentally adding duplicate 170import statements. It is also a rarely known feature, which may 171contribute to confusion. 172 173Do note that sometimes, this feature may be used 174intentionally (see for example 175https://github.com/golang/go/commit/3409ce39bfd7584523b7a8c150a310cea92d879d) 176– if you want to allow this pattern in your code base, you're 177advised to disable this check.`, 178 Since: "2020.1", 179 }, 180 181 "ST1020": { 182 Title: "The documentation of an exported function should start with the function's name", 183 Text: `Doc comments work best as complete sentences, which 184allow a wide variety of automated presentations. The first sentence 185should be a one-sentence summary that starts with the name being 186declared. 187 188If every doc comment begins with the name of the item it describes, 189you can use the doc subcommand of the go tool and run the output 190through grep. 191 192See https://golang.org/doc/effective_go.html#commentary for more 193information on how to write good documentation.`, 194 Since: "2020.1", 195 NonDefault: true, 196 }, 197 198 "ST1021": { 199 Title: "The documentation of an exported type should start with type's name", 200 Text: `Doc comments work best as complete sentences, which 201allow a wide variety of automated presentations. The first sentence 202should be a one-sentence summary that starts with the name being 203declared. 204 205If every doc comment begins with the name of the item it describes, 206you can use the \'doc\' subcommand of the \'go\' tool and run the output 207through grep. 208 209See https://golang.org/doc/effective_go.html#commentary for more 210information on how to write good documentation.`, 211 Since: "2020.1", 212 NonDefault: true, 213 }, 214 215 "ST1022": { 216 Title: "The documentation of an exported variable or constant should start with variable's name", 217 Text: `Doc comments work best as complete sentences, which 218allow a wide variety of automated presentations. The first sentence 219should be a one-sentence summary that starts with the name being 220declared. 221 222If every doc comment begins with the name of the item it describes, 223you can use the doc subcommand of the go tool and run the output 224through grep. 225 226See https://golang.org/doc/effective_go.html#commentary for more 227information on how to write good documentation.`, 228 Since: "2020.1", 229 NonDefault: true, 230 }, 231 232 "ST1023": { 233 Title: "Redundant type in variable declaration", 234 Since: "2021.1", 235 NonDefault: true, 236 }, 237}) 238