3 import "honnef.co/go/tools/analysis/lint"
5 var Docs = map[string]*lint.Documentation{
7 Title: `Invalid regular expression`,
12 Title: `Invalid template`,
17 Title: `Invalid format in time.Parse`,
22 Title: `Unsupported argument to functions in encoding/binary`,
23 Text: `The encoding/binary package can only serialize types with known sizes.
24 This precludes the use of the int and uint types, as their sizes
25 differ on different architectures. Furthermore, it doesn't support
26 serializing maps, channels, strings, or functions.
28 Before Go 1.8, bool wasn't supported, either.`,
33 Title: `Suspiciously small untyped constant in time.Sleep`,
34 Text: `The time.Sleep function takes a time.Duration as its only argument.
35 Durations are expressed in nanoseconds. Thus, calling time.Sleep(1)
36 will sleep for 1 nanosecond. This is a common source of bugs, as sleep
37 functions in other languages often accept seconds or milliseconds.
39 The time package provides constants such as time.Second to express
40 large durations. These can be combined with arithmetic to express
41 arbitrary durations, for example '5 * time.Second' for 5 seconds.
43 If you truly meant to sleep for a tiny amount of time, use
44 'n * time.Nanosecond' to signal to Staticcheck that you did mean to sleep
45 for some amount of nanoseconds.`,
50 Title: `Invalid first argument to exec.Command`,
51 Text: `os/exec runs programs directly (using variants of the fork and exec
52 system calls on Unix systems). This shouldn't be confused with running
53 a command in a shell. The shell will allow for features such as input
54 redirection, pipes, and general scripting. The shell is also
55 responsible for splitting the user's input into a program name and its
56 arguments. For example, the equivalent to
62 exec.Command("ls", "/", "/tmp")
64 If you want to run a command in a shell, consider using something like
65 the following – but be aware that not all systems, particularly
66 Windows, will have a /bin/sh program:
68 exec.Command("/bin/sh", "-c", "ls | grep Awesome")`,
73 Title: `Printf with dynamic first argument and no further arguments`,
74 Text: `Using fmt.Printf with a dynamic first argument can lead to unexpected
75 output. The first argument is a format string, where certain character
76 combinations have special meaning. If, for example, a user were to
77 enter a string such as
81 and you printed it with
85 it would lead to the following output:
87 Interest rate: 5%!(NOVERB).
89 Similarly, forming the first parameter via string concatenation with
90 user input should be avoided for the same reason. When printing user
91 input, either use a variant of fmt.Print, or use the %s Printf verb
92 and pass the string as an argument.`,
97 Title: `Invalid URL in net/url.Parse`,
102 Title: `Non-canonical key in http.Header map`,
103 Text: `Keys in http.Header maps are canonical, meaning they follow a specific
104 combination of uppercase and lowercase letters. Methods such as
105 http.Header.Add and http.Header.Del convert inputs into this canonical
106 form before manipulating the map.
108 When manipulating http.Header maps directly, as opposed to using the
109 provided methods, care should be taken to stick to canonical form in
110 order to avoid inconsistencies. The following piece of code
111 demonstrates one such inconsistency:
114 h["etag"] = []string{"1234"}
115 h.Add("etag", "5678")
119 // map[Etag:[5678] etag:[1234]]
121 The easiest way of obtaining the canonical form of a key is to use
122 http.CanonicalHeaderKey.`,
127 Title: `(*regexp.Regexp).FindAll called with n == 0, which will always return zero results`,
128 Text: `If n >= 0, the function returns at most n matches/submatches. To
129 return all results, specify a negative number.`,
134 Title: `Various methods in the strings package expect valid UTF-8, but invalid input is provided`,
139 Title: `A nil context.Context is being passed to a function, consider using context.TODO instead`,
144 Title: `io.Seeker.Seek is being called with the whence constant as the first argument, but it should be the second`,
149 Title: `Non-pointer value passed to Unmarshal or Decode`,
154 Title: `Using time.Tick in a way that will leak. Consider using time.NewTicker, and only use time.Tick in tests, commands and endless functions`,
159 Title: `Trapping a signal that cannot be trapped`,
160 Text: `Not all signals can be intercepted by a process. Speficially, on
161 UNIX-like systems, the syscall.SIGKILL and syscall.SIGSTOP signals are
162 never passed to the process, but instead handled directly by the
163 kernel. It is therefore pointless to try and handle these signals.`,
168 Title: `Channels used with os/signal.Notify should be buffered`,
169 Text: `The os/signal package uses non-blocking channel sends when delivering
170 signals. If the receiving end of the channel isn't ready and the
171 channel is either unbuffered or full, the signal will be dropped. To
172 avoid missing signals, the channel should be buffered and of the
173 appropriate size. For a channel used for notification of just one
174 signal value, a buffer of size 1 is sufficient.`,
179 Title: `strings.Replace called with n == 0, which does nothing`,
180 Text: `With n == 0, zero instances will be replaced. To replace all
181 instances, use a negative number, or use strings.ReplaceAll.`,
186 Title: `Using a deprecated function, variable, constant or field`,
191 Title: `Using an invalid host:port pair with a net.Listen-related function`,
196 Title: `Using bytes.Equal to compare two net.IP`,
197 Text: `A net.IP stores an IPv4 or IPv6 address as a slice of bytes. The
198 length of the slice for an IPv4 address, however, can be either 4 or
199 16 bytes long, using different ways of representing IPv4 addresses. In
200 order to correctly compare two net.IPs, the net.IP.Equal method should
201 be used, as it takes both representations into account.`,
206 Title: `Modifying the buffer in an io.Writer implementation`,
207 Text: `Write must not modify the slice data, even temporarily.`,
212 Title: `A string cutset contains duplicate characters`,
213 Text: `The strings.TrimLeft and strings.TrimRight functions take cutsets, not
214 prefixes. A cutset is treated as a set of characters to remove from a
217 strings.TrimLeft("42133word", "1234"))
219 will result in the string "word" – any characters that are 1, 2, 3 or
220 4 are cut from the left of the string.
222 In order to remove one string from another, use strings.TrimPrefix instead.`,
227 Title: `It is not possible to use (*time.Timer).Reset's return value correctly`,
232 Title: `Cannot marshal channels or functions`,
237 Title: `Atomic access to 64-bit variable must be 64-bit aligned`,
238 Text: `On ARM, x86-32, and 32-bit MIPS, it is the caller's responsibility to
239 arrange for 64-bit alignment of 64-bit words accessed atomically. The
240 first word in a variable or in an allocated struct, array, or slice
241 can be relied upon to be 64-bit aligned.
243 You can use the structlayout tool to inspect the alignment of fields
249 Title: `sort.Slice can only be used on slices`,
250 Text: `The first argument of sort.Slice must be a slice.`,
255 Title: `Inappropriate key in call to context.WithValue`,
256 Text: `The provided key must be comparable and should not be
257 of type string or any other built-in type to avoid collisions between
258 packages using context. Users of WithValue should define their own
261 To avoid allocating when assigning to an interface{},
262 context keys often have concrete type struct{}. Alternatively,
263 exported context key variables' static type should be a pointer or
269 Title: `sync.WaitGroup.Add called inside the goroutine, leading to a race condition`,
274 Title: `Empty critical section, did you mean to defer the unlock?`,
275 Text: `Empty critical sections of the kind
280 are very often a typo, and the following was intended instead:
285 Do note that sometimes empty critical sections can be useful, as a
286 form of signaling to wait on another goroutine. Many times, there are
287 simpler ways of achieving the same effect. When that isn't the case,
288 the code should be amply commented to avoid confusion. Combining such
289 comments with a //lint:ignore directive can be used to suppress this
290 rare false positive.`,
295 Title: `Called testing.T.FailNow or SkipNow in a goroutine, which isn't allowed`,
300 Title: `Deferred Lock right after locking, likely meant to defer Unlock instead`,
305 Title: `TestMain doesn't call os.Exit, hiding test failures`,
306 Text: `Test executables (and in turn 'go test') exit with a non-zero status
307 code if any tests failed. When specifying your own TestMain function,
308 it is your responsibility to arrange for this, by calling os.Exit with
309 the correct code. The correct code is returned by (*testing.M).Run, so
310 the usual way of implementing TestMain is to end it with
316 Title: `Assigning to b.N in benchmarks distorts the results`,
317 Text: `The testing package dynamically sets b.N to improve the reliability of
318 benchmarks and uses it in computations to determine the duration of a
319 single operation. Benchmark code must not alter b.N as this would
325 Title: `Boolean expression has identical expressions on both sides`,
330 Title: `&*x gets simplified to x, it does not copy x`,
335 Title: `Comparing strings with known different sizes has predictable results`,
340 Title: `Comparing unsigned values against negative values is pointless`,
345 Title: `The loop exits unconditionally after one iteration`,
350 Title: `Field assignment that will never be observed. Did you mean to use a pointer receiver?`,
355 Title: `A value assigned to a variable is never read before being overwritten. Forgotten error check or dead code?`,
360 Title: `The variable in the loop condition never changes, are you incrementing the wrong variable?`,
365 Title: `A function argument is overwritten before its first use`,
370 Title: `The result of append will never be observed anywhere`,
375 Title: `Break statement with no effect. Did you mean to break out of an outer loop?`,
380 Title: `Comparing a value against NaN even though no value is equal to NaN`,
385 Title: `Negating a boolean twice (!!b) is the same as writing b. This is either redundant, or a typo.`,
390 Title: `An if/else if chain has repeated conditions and no side-effects; if the condition didn't match the first time, it won't match the second time, either`,
395 Title: `Calling functions like math.Ceil on floats converted from integers doesn't do anything useful`,
400 Title: `Certain bitwise operations, such as x ^ 0, do not do anything useful`,
405 Title: `A pure function's return value is discarded, making the call pointless`,
410 Title: `Self-assignment of variables`,
415 Title: `Multiple, identical build constraints in the same file`,
420 Title: `Unreachable case clause in a type switch`,
421 Text: `In a type switch like the following
424 func (T) Read(b []byte) (int, error) { return 0, nil }
426 var v interface{} = T{}
435 the second case clause can never be reached because T implements
436 io.Reader and case clauses are evaluated in source order.
441 func (T) Read(b []byte) (int, error) { return 0, nil }
442 func (T) Close() error { return nil }
444 var v interface{} = T{}
453 Even though T has a Close method and thus implements io.ReadCloser,
454 io.Reader will always match first. The method set of io.Reader is a
455 subset of io.ReadCloser. Thus it is impossible to match the second
456 case without matching the first case.
459 Structurally equivalent interfaces
461 A special case of the previous example are structurally identical
462 interfaces. Given these declarations
467 func doSomething() error {
468 err, ok := doAnotherThing()
476 the following type switch will have an unreachable case clause:
478 switch doSomething().(type) {
485 T will always match before V because they are structurally equivalent
486 and therefore doSomething()'s return value implements both.`,
491 Title: `x = append(y) is equivalent to x = y`,
496 Title: `Comparing the address of a variable against nil`,
497 Text: `Code such as 'if &x == nil' is meaningless, because taking the address of a variable always yields a non-nil pointer.`,
502 Title: `Impossible comparison of interface value with untyped nil`,
503 Text: `Under the covers, interfaces are implemented as two elements, a
504 type T and a value V. V is a concrete value such as an int,
505 struct or pointer, never an interface itself, and has type T. For
506 instance, if we store the int value 3 in an interface, the
507 resulting interface value has, schematically, (T=int, V=3). The
508 value V is also known as the interface's dynamic value, since a
509 given interface variable might hold different values V (and
510 corresponding types T) during the execution of the program.
512 An interface value is nil only if the V and T are both
513 unset, (T=nil, V is not set), In particular, a nil interface will
514 always hold a nil type. If we store a nil pointer of type *int
515 inside an interface value, the inner type will be *int regardless
516 of the value of the pointer: (T=*int, V=nil). Such an interface
517 value will therefore be non-nil even when the pointer value V
520 This situation can be confusing, and arises when a nil value is
521 stored inside an interface value such as an error return:
523 func returnsError() error {
528 return p // Will always return a non-nil error.
531 If all goes well, the function returns a nil p, so the return
532 value is an error interface value holding (T=*MyError, V=nil).
533 This means that if the caller compares the returned error to nil,
534 it will always look as if there was an error even if nothing bad
535 happened. To return a proper nil error to the caller, the
536 function must return an explicit nil:
538 func returnsError() error {
545 It's a good idea for functions that return errors always to use
546 the error type in their signature (as we did above) rather than a
547 concrete type such as *MyError, to help guarantee the error is
548 created correctly. As an example, os.Open returns an error even
549 though, if not nil, it's always of concrete type *os.PathError.
551 Similar situations to those described here can arise whenever
552 interfaces are used. Just keep in mind that if any concrete value
553 has been stored in the interface, the interface will not be nil.
554 For more information, see The Laws of
555 Reflection (https://golang.org/doc/articles/laws_of_reflection.html).
557 This text has been copied from
558 https://golang.org/doc/faq#nil_error, licensed under the Creative
559 Commons Attribution 3.0 License.`,
564 Title: `Assignment to nil map`,
569 Title: `Defering Close before checking for a possible error`,
574 Title: `The empty for loop (for {}) spins and can block the scheduler`,
579 Title: `Defers in infinite loops will never execute`,
580 Text: `Defers are scoped to the surrounding function, not the surrounding
581 block. In a function that never returns, i.e. one containing an
582 infinite loop, defers will never execute.`,
587 Title: `for { select { ... with an empty default branch spins`,
592 Title: `The finalizer references the finalized object, preventing garbage collection`,
593 Text: `A finalizer is a function associated with an object that runs when the
594 garbage collector is ready to collect said object, that is when the
595 object is no longer referenced by anything.
597 If the finalizer references the object, however, it will always remain
598 as the final reference to that object, preventing the garbage
599 collector from collecting the object. The finalizer will never run,
600 and the object will never be collected, leading to a memory leak. That
601 is why the finalizer should instead use its first argument to operate
602 on the object. That way, the number of references can temporarily go
603 to zero before the object is being passed to the finalizer.`,
608 Title: `Slice index out of bounds`,
613 Title: `Infinite recursive call`,
614 Text: `A function that calls itself recursively needs to have an exit
615 condition. Otherwise it will recurse forever, until the system runs
618 This issue can be caused by simple bugs such as forgetting to add an
619 exit condition. It can also happen "on purpose". Some languages have
620 tail call optimization which makes certain infinite recursive calls
621 safe to use. Go, however, does not implement TCO, and as such a loop
622 should be used instead.`,
627 Title: `Invalid struct tag`,
632 Title: `Invalid Printf call`,
637 Title: `Impossible type assertion`,
639 Text: `Some type assertions can be statically proven to be
640 impossible. This is the case when the method sets of both
641 arguments of the type assertion conflict with each other, for
642 example by containing the same method with different
645 The Go compiler already applies this check when asserting from an
646 interface value to a concrete type. If the concrete type misses
647 methods from the interface, or if function signatures don't match,
648 then the type assertion can never succeed.
650 This check applies the same logic when asserting from one interface to
651 another. If both interface types contain the same method but with
652 different signatures, then the type assertion can never succeed,
659 Title: `Possible nil pointer dereference`,
661 Text: `A pointer is being dereferenced unconditionally, while
662 also being checked against nil in another place. This suggests that
663 the pointer may be nil and dereferencing it may panic. This is
664 commonly a result of improperly ordered code or missing return
665 statements. Consider the following examples:
670 // This nil check is equally important for the previous dereference
676 func TestFoo(t *testing.T) {
679 t.Errorf("nil pointer received")
682 // t.Errorf does not abort the test, so if x is nil, the next line will panic.
686 Staticcheck tries to deduce which functions abort control flow.
687 For example, it is aware that a function will not continue
688 execution after a call to panic or log.Fatal. However, sometimes
689 this detection fails, in particular in the presence of
690 conditionals. Consider the following example:
692 func Log(msg string, level int) {
694 if level == levelFatal {
699 func Fatal(msg string) {
705 Fatal("unexpected nil pointer")
710 Staticcheck will flag the dereference of x, even though it is perfectly
711 safe. Staticcheck is not able to deduce that a call to
712 Fatal will exit the program. For the time being, the easiest
713 workaround is to modify the definition of Fatal like so:
715 func Fatal(msg string) {
720 We also hard-code functions from common logging packages such as
721 logrus. Please file an issue if we're missing support for a
727 Title: "Passing odd-sized slice to function expecting even size",
728 Text: `Some functions that take slices as parameters expect the slices to have an even number of elements.
729 Often, these functions treat elements in a slice as pairs.
730 For example, strings.NewReplacer takes pairs of old and new strings,
731 and calling it with an odd number of elements would be an error.`,
736 Title: `Using regexp.Match or related in a loop, should use regexp.Compile`,
741 Title: `Missing an optimization opportunity when indexing maps by byte slices`,
743 Text: `Map keys must be comparable, which precludes the use of byte slices.
744 This usually leads to using string keys and converting byte slices to
747 Normally, a conversion of a byte slice to a string needs to copy the data and
748 causes allocations. The compiler, however, recognizes m[string(b)] and
749 uses the data of b directly, without copying it, because it knows that
750 the data can't change during the map lookup. This leads to the
751 counter-intuitive situation that
757 will be less efficient than
759 println(m[string(b)])
760 println(m[string(b)])
762 because the first version needs to copy and allocate, while the second
765 For some history on this optimization, check out commit
766 f5f5a8b6209f84961687d993b93ea0d397f5d5bf in the Go repository.`,
771 Title: `Storing non-pointer values in sync.Pool allocates memory`,
772 Text: `A sync.Pool is used to avoid unnecessary allocations and reduce the
773 amount of work the garbage collector has to do.
775 When passing a value that is not a pointer to a function that accepts
776 an interface, the value needs to be placed on the heap, which means an
777 additional allocation. Slices are a common thing to put in sync.Pools,
778 and they're structs with 3 fields (length, capacity, and a pointer to
779 an array). In order to avoid the extra allocation, one should store a
780 pointer to the slice instead.
782 See the comments on https://go-review.googlesource.com/c/go/+/24371
783 that discuss this problem.`,
788 Title: `Converting a string to a slice of runes before ranging over it`,
789 Text: `You may want to loop over the runes in a string. Instead of converting
790 the string to a slice of runes and looping over that, you can loop
791 over the string itself. That is,
793 for _, r := range s {}
797 for _, r := range []rune(s) {}
799 will yield the same values. The first version, however, will be faster
800 and avoid unnecessary memory allocations.
802 Do note that if you are interested in the indices, ranging over a
803 string and over a slice of runes will yield different indices. The
804 first one yields byte offsets, while the second one yields indices in
805 the slice of runes.`,
810 Title: `Inefficient string comparison with strings.ToLower or strings.ToUpper`,
811 Text: `Converting two strings to the same case and comparing them like so
813 if strings.ToLower(s1) == strings.ToLower(s2) {
817 is significantly more expensive than comparing them with
818 strings.EqualFold(s1, s2). This is due to memory usage as well as
819 computational complexity.
821 strings.ToLower will have to allocate memory for the new strings, as
822 well as convert both strings fully, even if they differ on the very
823 first byte. strings.EqualFold, on the other hand, compares the strings
824 one character at a time. It doesn't need to create two intermediate
825 strings and can return as soon as the first non-matching character has
828 For a more in-depth explanation of this issue, see
829 https://blog.digitalocean.com/how-to-efficiently-compare-strings-in-go/`,
834 Title: `Defers in range loops may not run when you expect them to`,
839 Title: `Using a non-octal os.FileMode that looks like it was meant to be in octal.`,
844 Title: `Empty body in an if or else branch`,
849 Title: `Only the first constant has an explicit type`,
851 Text: `In a constant declaration such as the following:
858 the constant Second does not have the same type as the constant First.
859 This construct shouldn't be confused with
866 where First and Second do indeed have the same type. The type is only
867 passed on when no explicit value is assigned to the constant.
869 When declaring enumerations with explicit values it is therefore
870 important not to write
873 EnumFirst EnumType = 1
878 This discrepancy in types can cause various confusing behaviors and
882 Wrong type in variable declarations
884 The most obvious issue with such incorrect enumerations expresses
885 itself as a compile error:
894 func fn(useFirst bool) {
901 fails to compile with
903 ./const.go:11:5: cannot use EnumFirst (type uint8) as type int in assignment
908 A more subtle issue occurs with types that have methods and optional
909 interfaces. Consider the following:
917 func (e Enum) String() string {
927 fmt.Println(EnumFirst)
928 fmt.Println(EnumSecond)
931 This code will output
936 as EnumSecond has no explicit type, and thus defaults to int.`,
941 Title: `Trying to marshal a struct with no public fields nor custom marshaling`,
942 Text: `The encoding/json and encoding/xml packages only operate on exported
943 fields in structs, not unexported ones. It is usually an error to try
944 to (un)marshal structs that only consist of unexported fields.
946 This check will not flag calls involving types that define custom
947 marshaling behavior, e.g. via MarshalJSON methods. It will also not
948 flag empty structs.`,
953 Title: `Dubious bit shifting of a fixed size integer value`,
954 Text: `Bit shifting a value past its size will always clear the value.
961 will always result in 0.
963 This check flags bit shifiting operations on fixed size integer values only.
964 That is, int, uint and uintptr are never flagged to avoid potential false
965 positives in somewhat exotic but valid bit twiddling tricks:
967 // Clear any value above 32 bits if integers are more than 32 bits.
projects / dotfiles / .git / blob