Debian Codegraph @

website/content/docs/checks.html

raw
1 ---
2 title: "Checks"
3 description: "Explanations for all checks in Staticcheck"
4 menu:
5 main:
6 weight: 2
7 pre: <i class='fas fa-tasks'></i>
8 ---
9 {{< all-checks.inline >}}
10 {{ define "category-list" }}
11 {{ range $name := index $.p.Site.Data.checks.ByCategory $.cat }}
12 {{ $check := index $.p.Site.Data.checks.Checks $name }}
13 <tr>
14 <td><a href="#{{ $name }}">{{ $name }}</a></td>
15 <td>{{ $check.TitleMarkdown | markdownify }}</td>
16 </tr>
17 {{ end }}
18 {{ end }}
19
20
21 {{ define "category" }}
22 {{ range $name := index $.p.Site.Data.checks.ByCategory .cat }}
23 {{ $check := index $.p.Site.Data.checks.Checks $name }}
24 <h4 id="{{ $name }}">{{ $name }} - {{ $check.TitleMarkdown | markdownify }}{{ if $check.NonDefault }} <span class="badge badge-primary">non-default</span>{{ end }}</h4>
25 {{ $check.TextMarkdown | $.p.Page.RenderString (dict "display" "block") }}
26
27 {{ if $check.Before }}
28 <p class="before-after"><strong>Before:</strong></p>
29 {{ highlight $check.Before "go" "" }}
30 {{ end }}
31
32 {{ if $check.After }}
33 <p class="before-after"><strong>After:</strong></p>
34 {{ highlight $check.After "go" "" }}
35 {{ end }}
36
37
38 <dl>
39 <dt>Available since</dt>
40 <dd>{{ $check.Since }}</dd>
41
42 {{ if $check.Options }}
43 <dt>Options</dt>
44 <dd>
45 <ul>
46 {{ range $opt := $check.Options -}}
47 <li><a href="{{ relref $.p (printf "/docs/configuration/options#%s" $opt) }}">{{ $opt }}</a></li>
48 {{ end }}
49 </ul>
50 </dd>
51 {{ end }}
52 </dl>
53 {{ end }}
54 {{ end }}
55
56 {{ $categoryNames := slice "SA" "SA1" "SA2" "SA3" "SA4" "SA5" "SA6" "SA9" "S" "S1" "ST" "ST1" "QF" "QF1" }}
57 {{ $categories := dict
58 "SA" (dict "name" "SA" "title" "<code>staticcheck</code>")
59 "SA1" (dict "name" "SA1" "title" "Various misuses of the standard library")
60 "SA2" (dict "name" "SA2" "title" "Concurrency issues")
61 "SA3" (dict "name" "SA3" "title" "Testing issues")
62 "SA4" (dict "name" "SA4" "title" "Code that isn't really doing anything")
63 "SA5" (dict "name" "SA5" "title" "Correctness issues")
64 "SA6" (dict "name" "SA6" "title" "Performance issues")
65 "SA9" (dict "name" "SA9" "title" "Dubious code constructs that have a high probability of being wrong")
66
67 "S" (dict "name" "S" "title" "<code>simple</code>")
68 "S1" (dict "name" "S1" "title" "Code simplifications")
69
70 "ST" (dict "name" "ST" "title" "<code>stylecheck</code>")
71 "ST1" (dict "name" "ST1" "title" "Stylistic issues")
72
73 "QF" (dict "name" "QF" "title" "<code>quickfix</code>")
74 "QF1" (dict "name" "QF1" "title" "Quickfixes")
75 }}
76
77 <table>
78 <thead>
79 <tr>
80 <th>Check</th>
81 <th>Short description</th>
82 </tr>
83 </thead>
84
85 <tbody>
86 {{ range $name := $categoryNames }}
87 {{ $cat := index $categories $name }}
88 <tr><th><a href="#{{ $name }}">{{ $cat.name }}</a></th><th>{{ $cat.title }}</th></tr>
89 {{ template "category-list" (dict "p" $ "cat" $cat.name) }}
90 {{ end }}
91 </tbody>
92 </tr>
93 </table>
94
95 {{ define "category-header" }}
96 <h2 id="{{ .name }}">{{ .name }} – {{ .title }}</h2>
97 {{ end }}
98
99 {{ define "subcategory-header" }}
100 <h3 id="{{ .name }}">{{ .name }} – {{ .title }}</h3>
101 {{ end }}
102
103 {{ template "category-header" (index $categories "SA") }}
104 <p>
105 The SA category of checks, codenamed <code>staticcheck</code>, contains all checks that are concerned with the correctness of code.
106 </p>
107 {{ template "subcategory-header" (index $categories "SA1") }}
108 <p>
109 Checks in this category deal with misuses of the standard library.
110 This tends to involve incorrect function arguments
111 or violating other invariants laid out by the standard library's documentation.
112 </p>
113 {{ template "category" (dict "p" $ "cat" "SA1") }}
114
115
116 {{ template "subcategory-header" (index $categories "SA2") }}
117 <p>
118 Checks in this category find concurrency bugs.
119 </p>
120 {{ template "category" (dict "p" $ "cat" "SA2") }}
121
122
123 {{ template "subcategory-header" (index $categories "SA3") }}
124 <p>
125 Checks in this category find issues in tests and benchmarks.
126 </p>
127 {{ template "category" (dict "p" $ "cat" "SA3") }}
128
129
130 {{ template "subcategory-header" (index $categories "SA4") }}
131 <p>
132 Checks in this category point out code that doesn't have any meaningful effect on a program's execution.
133 Usually this means that the programmer thought the code would do one thing while in reality it does something else.
134 </p>
135 {{ template "category" (dict "p" $ "cat" "SA4") }}
136
137
138 {{ template "subcategory-header" (index $categories "SA5") }}
139 <p>
140 Checks in this category find assorted bugs and crashes.
141 </p>
142 {{ template "category" (dict "p" $ "cat" "SA5") }}
143
144
145 {{ template "subcategory-header" (index $categories "SA6") }}
146 <p>
147 Checks in this category find code that can be trivially made faster.
148 </p>
149 {{ template "category" (dict "p" $ "cat" "SA6") }}
150
151
152 {{ template "subcategory-header" (index $categories "SA9") }}
153 <p>
154 Checks in this category find code that is probably wrong.
155 Unlike checks in the other <code>SA</code> categories,
156 checks in <code>SA9</code> have a slight chance of reporting false positives.
157 However, even false positives will point at code that is confusing and that should probably be refactored.
158 </p>
159 {{ template "category" (dict "p" $ "cat" "SA9") }}
160
161 {{ template "category-header" (index $categories "S") }}
162 <p>
163 The S category of checks, codenamed <code>simple</code>, contains all checks that are concerned with simplifying code.
164 </p>
165
166 {{ template "subcategory-header" (index $categories "S1") }}
167 <p>
168 Checks in this category find code that is unnecessarily complex and that can be trivially simplified.
169 </p>
170 {{ template "category" (dict "p" $ "cat" "S1") }}
171
172 {{ template "category-header" (index $categories "ST") }}
173 <p>
174 The ST category of checks, codenamed <code>stylecheck</code>, contains all checks that are concerned with stylistic issues.
175 </p>
176
177 {{ template "subcategory-header" (index $categories "ST1") }}
178 <p>
179 The rules contained in this category are primarily derived from the <a href="https://go.dev/wiki/CodeReviewComments">Go wiki</a> and represent community consensus.
180 </p>
181
182 <p>
183 Some checks are very pedantic and disabled by default.
184 You may want to <a href="{{ relref . "/docs/configuration/options#checks" }}">tweak which checks from this category run</a>, based on your project's needs.
185 </p>
186 {{ template "category" (dict "p" $ "cat" "ST1") }}
187
188 {{ template "category-header" (index $categories "QF") }}
189 <p>
190 The QF category of checks, codenamed <code>quickfix</code>, contains checks that are used as part of <em>gopls</em> for automatic refactorings.
191 In the context of gopls, diagnostics of these checks will usually show up as hints, sometimes as information-level diagnostics.
192 </p>
193 {{ template "subcategory-header" (index $categories "QF1") }}
194 {{ template "category" (dict "p" $ "cat" "QF1") }}
195
196 {{< /all-checks.inline >}}