diff --git a/go/best-practices.md b/go/best-practices.md index 0c2d598..d31eeb1 100644 --- a/go/best-practices.md +++ b/go/best-practices.md @@ -823,7 +823,8 @@ func handlePet(...) { ``` Do not attempt to distinguish errors based on their string form. (See -https://google.github.io/styleguide/go/index.html#gotip for more.) +[Go Tip #13: Designing Errors for Checking](https://google.github.io/styleguide/go/index.html#gotip) +for more.) ```go // Bad: @@ -1492,11 +1493,11 @@ func (c *Client) Get(url string) (resp *Response, err error) ### Preview -Go features a documentation server: -https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite. It is recommended to -preview the documentation your code produces both before and during the code -review process. This helps to validate that the [godoc formatting] is rendered -correctly. +Go features a +[documentation server](https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite). It +is recommended to preview the documentation your code produces both before and +during the code review process. This helps to validate that the +[godoc formatting] is rendered correctly. [godoc formatting]: #godoc-formatting @@ -2554,8 +2555,8 @@ fails, the user should know where, and why. **Tip:** Go 1.14 introduced a [`t.Cleanup`] function that can be used to register cleanup functions that run when your test completes. The function also works with test helpers. See -https://google.github.io/styleguide/go/index.html#gotip for guidance on -simplifying test helpers. +[GoTip #4: Cleaning Up Your Tests](https://google.github.io/styleguide/go/index.html#gotip) +for guidance on simplifying test helpers. The snippet below in a fictional file called `paint_test.go` demonstrates how `(*testing.T).Helper` influences failure reporting in a Go test: diff --git a/go/decisions.md b/go/decisions.md index c2d8858..1b8c6c3 100644 --- a/go/decisions.md +++ b/go/decisions.md @@ -30,20 +30,19 @@ This document is **not exhaustive** and will grow over time. In cases where [the core style guide](guide) contradicts the advice given here, **the style guide takes precedence**, and this document should be updated accordingly. -See https://google.github.io/styleguide/go#about for the full set of Go Style -documents. +See [the Overview](https://google.github.io/styleguide/go#about) for the full +set of Go Style documents. The following sections have moved from style decisions to another part of the guide: -* **MixedCaps**: see https://google.github.io/styleguide/go/guide#mixed-caps +* **MixedCaps**: see [guide#mixed-caps](guide#mixed-caps) -* **Formatting**: see https://google.github.io/styleguide/go/guide#formatting +* **Formatting**: see [guide#formatting](guide#formatting) -* **Line Length**: see - https://google.github.io/styleguide/go/guide#line-length +* **Line Length**: see [guide#line-length](guide#line-length) @@ -116,7 +115,7 @@ wherever possible for consistency. -See also: https://go.dev/blog/package-names +See also: [Go blog post about package names](https://go.dev/blog/package-names). @@ -1494,7 +1493,7 @@ import ( ) ldb := leveldb.Open("/my/table", &db.Options{ - BlockSize int: 1<<16, + BlockSize: 1<<16, ErrorIfDBExists: true, // These fields all have their zero values. @@ -1517,7 +1516,7 @@ import ( ) ldb := leveldb.Open("/my/table", &db.Options{ - BlockSize int: 1<<16, + BlockSize: 1<<16, ErrorIfDBExists: true, }) ``` @@ -2820,7 +2819,7 @@ Exceptions are: Code using gRPC streaming accesses a context from a `Context()` method in the generated server type, which implements `grpc.ServerStream`. See - https://grpc.io/docs/languages/go/generated-code/. + [gRPC Generated Code documentation](https://grpc.io/docs/languages/go/generated-code/). * In entrypoint functions (see below for examples of such functions), use [`context.Background()`](https://pkg.go.dev/context/#Background). @@ -2866,8 +2865,8 @@ and readability review. Code in the Google codebase that must spawn background operations which can run after the parent context has been cancelled can use an internal package for -detachment. Follow https://github.com/golang/go/issues/40221 for discussions on -an open source alternative. +detachment. Follow [issue #40221](https://github.com/golang/go/issues/40221) for +discussions on an open source alternative. Since contexts are immutable, it is fine to pass the same context to multiple calls that share the same deadline, cancellation signal, credentials, parent @@ -3217,7 +3216,7 @@ It is user-configurable and should serve most comparison needs. [language-defined comparisons]: http://golang.org/ref/spec#Comparison_operators [`cmp`]: https://pkg.go.dev/github.com/google/go-cmp/cmp -[`cmp.Equal`]: https://pkg.go.dev/github.com/google/go-cmp/cmp/cmp#Equal +[`cmp.Equal`]: https://pkg.go.dev/github.com/google/go-cmp/cmp#Equal [`cmp.Diff`]: https://pkg.go.dev/github.com/google/go-cmp/cmp/cmp#Diff [`protocmp.Transform`]: https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp#Transform @@ -3394,7 +3393,8 @@ See also The standard Go testing library offers a facility to [define subtests]. This allows flexibility in setup and cleanup, controlling parallelism, and test filtering. Subtests can be useful (particularly for table-driven tests), but -using them is not mandatory. See also https://blog.golang.org/subtests. +using them is not mandatory. See also the +[Go blog post about subtests](https://blog.golang.org/subtests). Subtests should not depend on the execution of other cases for success or initial state, because subtests are expected to be able to be run individually diff --git a/go/index.md b/go/index.md index 027a665..4921c7d 100644 --- a/go/index.md +++ b/go/index.md @@ -35,12 +35,12 @@ Document | Link | Pr ### Documents -1. The **Style Guide** (https://google.github.io/styleguide/go/guide) outlines +1. The **[Style Guide](https://google.github.io/styleguide/go/guide)** outlines the foundation of Go style at Google. This document is definitive and is used as the basis for the recommendations in Style Decisions and Best Practices. -1. **Style Decisions** (https://google.github.io/styleguide/go/decisions) is a +1. **[Style Decisions](https://google.github.io/styleguide/go/decisions)** is a more verbose document that summarizes decisions on specific style points and discusses the reasoning behind the decisions where appropriate. @@ -49,7 +49,7 @@ Document | Link | Pr individual Go programmers at Google should keep up-to-date with this document. -1. **Best Practices** (https://google.github.io/styleguide/go/best-practices) +1. **[Best Practices](https://google.github.io/styleguide/go/best-practices)** documents some of the patterns that have evolved over time that solve common problems, read well, and are robust to code maintenance needs.