Repository: go
Issue: wiki: CodeReviewComments: Error documentation
Labels: Documentation,NeedsDecision

## Problem

[Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) contains various bits of advice around errors:
- [Error Strings](https://github.com/golang/go/wiki/CodeReviewComments#error-strings)
- [Handle Errors](https://github.com/golang/go/wiki/CodeReviewComments#handle-errors)
- [In-Band Errors](https://github.com/golang/go/wiki/CodeReviewComments#in-band-errors)
- [Indent Error Flow](https://github.com/golang/go/wiki/CodeReviewComments#indent-error-flow)

However, there isn’t any good advice on how to deal with:
- defining sentinel errors and checking them with `errors.Is`,
- defining custom error types and checking them with `errors.As`,
- wrapping errors with additional context using fmt`.Errorf`.

In addition, the [Handle Errors](https://github.com/golang/go/wiki/CodeReviewComments#handle-errors) redirects readers to some obsolete advice in [Effective Go: Errors](https://golang.org/doc/effective_go#errors), which is highlighted by #45535. Since _Effective Go_ will likely be frozen in the near future, see #28782, we should update the link with something more modern.

This work is motivated by https://github.com/golang/go/issues/49172#issuecomment-954297660 where we realized that we need to discourage dependencies from doing error string comparisons, like [`.Error() == "..."`](https://sourcegraph.com/search?q=context:global+timeout:1m+lang:go+-file:_test.go%24+-file:%5Evendor/+.Error%28%29+%3D%3D+%22...%22&patternType=structural), so that corrections to error strings won’t break downstream programs.

## Proposal

The following items are proposed changes to consider, in no particular order:

- [ ] Change [**Handle Errors**](https://github.com/golang/go/wiki/CodeReviewComments#handle-errors) to point to [Working with Errors in Go 1.13 - go.dev](https://go.dev/blog/go1.13-errors).
- [ ] Be more specific in [**Handle Errors**](https://github.com/golang/go/wiki/CodeReviewComments#handle-errors) to mention checking with `errors.Is` and `errors.As`, with examples for common idioms.
- [ ] Change [**In-Band Errors**](https://github.com/golang/go/wiki/CodeReviewComments#in-band-errors) so it describes error wrapping with `fmt.Errorf`, since the current example encourages consumers to check the Error string for a substring.
- [ ] Add **Sentinel Errors** to discuss common sentinels like `io.EOF` and `sql.ErrNoRows`, declaring custom sentinels with `errors.New`, and recommend `errors.Is` for checking errors. I acknowledge that many of these errors are actually == equal, but that is subtly brittle for new Go programmers.
- [ ] Add **Error Types** that explains how to create a custom error type, referencing [Error handling in Upspin](https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html), and recommend using errors.As instead of a type assertion.
- [ ] Add **Wrapping Errors** to discuss how to use `fmt.Errorf` with `%w` to wrap an error with additional context, instead of returning the naked error.
- [ ] _Additional errors proposed in the comments below._

## Implementation

Drafts of each section will be included in the comments below. Please feel free to suggest changes to any of the proposed sections. Please also vote :+1: or :-1: to indicate whether we should include a given section.