diff --git a/CODEOWNERS b/CODEOWNERS index 7d1579e..2525d49 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -7,3 +7,4 @@ lispguide.xml @sfreilich pyguide.md @gpshead pylintrc @gpshead shellguide.md @dimo414 @eatnumber1 @vapier +/go/ @carrotman42 @gaal @matttproud diff --git a/README.md b/README.md index f1ce106..49c8af6 100644 --- a/README.md +++ b/README.md @@ -2,49 +2,60 @@ Every major open-source project has its own style guide: a set of conventions (sometimes arbitrary) about how to write code for that project. It is much -easier to understand a large codebase when all the code in it is in a -consistent style. +easier to understand a large codebase when all the code in it is in a consistent +style. “Style” covers a lot of ground, from “use camelCase for variable names” to “never use global variables” to “never use exceptions.” This project -([google/styleguide](https://github.com/google/styleguide)) links to the -style guidelines we use for Google code. If you are modifying a project that +([google/styleguide](https://github.com/google/styleguide)) links to the style +guidelines we use for Google code. If you are modifying a project that originated at Google, you may be pointed to this page to see the style guides that apply to that project. -This project holds the [C++ Style Guide][cpp], [C# Style Guide][csharp], -[Swift Style Guide][swift], [Objective-C Style Guide][objc], -[Java Style Guide][java], [Python Style Guide][py], [R Style Guide][r], -[Shell Style Guide][sh], [HTML/CSS Style Guide][htmlcss], -[JavaScript Style Guide][js], [TypeScript Style Guide][ts], [AngularJS Style Guide][angular], -[Common Lisp Style Guide][cl], and [Vim script Style Guide][vim]. This project -also contains [cpplint][cpplint], a tool to assist with style guide compliance, -and [google-c-style.el][emacs], an Emacs settings file for Google style. -If your project requires that you create a new XML document format, the [XML -Document Format Style Guide][xml] may be helpful. In addition to actual style -rules, it also contains advice on designing your own vs. adapting an existing -format, on XML instance document formatting, and on elements vs. attributes. +* [AngularJS Style Guide][angular] +* [Common Lisp Style Guide][cl] +* [C++ Style Guide][cpp] +* [C# Style Guide][csharp] +* [Go Style Guide][go] +* [HTML/CSS Style Guide][htmlcss] +* [JavaScript Style Guide][js] +* [Java Style Guide][java] +* [Objective-C Style Guide][objc] +* [Python Style Guide][py] +* [R Style Guide][r] +* [Shell Style Guide][sh] +* [Swift Style Guide][swift] +* [TypeScript Style Guide][ts] +* [Vim script Style Guide][vim] -The style guides in this project are licensed under the CC-By 3.0 License, -which encourages you to share these documents. -See [https://creativecommons.org/licenses/by/3.0/][ccl] for more details. +This project also contains [cpplint][cpplint], a tool to assist with style guide +compliance, and [google-c-style.el][emacs], an Emacs settings file for Google +style. -The following Google style guides live outside of this project: -[Go Code Review Comments][go] and [Effective Dart][dart]. +If your project requires that you create a new XML document format, the +[XML Document Format Style Guide][xml] may be helpful. In addition to actual +style rules, it also contains advice on designing your own vs. adapting an +existing format, on XML instance document formatting, and on elements vs. +attributes. +The style guides in this project are licensed under the CC-By 3.0 License, which +encourages you to share these documents. See +[https://creativecommons.org/licenses/by/3.0/][ccl] for more details. + +The following Google style guide lives outside of this project: +[Effective Dart][dart]. ## Contributing -With few exceptions, these style guides are copies of Google's internal style guides -to assist developers working on Google owned and originated open source projects. -Changes to the style guides are made to the internal style guides first and -eventually copied into the versions found here. **External contributions are -not accepted.** -Pull requests are regularly closed without comment. -Issues that raise questions, justify changes on technical merits, -or point out obvious mistakes may get some engagement and could in theory lead to changes, -but we are primarily optimizing for Google's internal needs. +With few exceptions, these style guides are copies of Google's internal style +guides to assist developers working on Google owned and originated open source +projects. Changes to the style guides are made to the internal style guides +first and eventually copied into the versions found here. **External +contributions are not accepted.** Pull requests are regularly closed without +comment. Issues that raise questions, justify changes on technical merits, or +point out obvious mistakes may get some engagement and could in theory lead to +changes, but we are primarily optimizing for Google's internal needs. Creative Commons License @@ -52,6 +63,7 @@ but we are primarily optimizing for Google's internal needs. [csharp]: https://google.github.io/styleguide/csharp-style.html [swift]: https://google.github.io/swift/ [objc]: objcguide.md +[go]: go/ [java]: https://google.github.io/styleguide/javaguide.html [py]: https://google.github.io/styleguide/pyguide.html [r]: https://google.github.io/styleguide/Rguide.html @@ -65,7 +77,5 @@ but we are primarily optimizing for Google's internal needs. [cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint [emacs]: https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el [xml]: https://google.github.io/styleguide/xmlstyle.html -[go]: https://golang.org/wiki/CodeReviewComments [dart]: https://www.dartlang.org/guides/language/effective-dart [ccl]: https://creativecommons.org/licenses/by/3.0/ - 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 87deefa..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. @@ -161,11 +161,17 @@ reviews. **Relevant Testing-on-the-Toilet articles** -* [https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html](Identifier Naming) -* [https://testing.googleblog.com/2013/03/testing-on-toilet-testing-state-vs.html](Testing State vs. Testing Interactions) -* [https://testing.googleblog.com/2014/05/testing-on-toilet-effective-testing.html](Effective Testing) -* [https://testing.googleblog.com/2014/05/testing-on-toilet-risk-driven-testing.html](Risk-driven Testing) -* [https://testing.googleblog.com/2015/01/testing-on-toilet-change-detector-tests.html](Change-detector Tests Considered Harmful) +* [TotT: Identifier Naming][tott-431] +* [TotT: Testing State vs. Testing Interactions][tott-281] +* [TotT: Effective Testing][tott-324] +* [TotT: Risk-driven Testing][tott-329] +* [TotT: Change-detector Tests Considered Harmful][tott-350] + +[tott-431]: https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html +[tott-281]: https://testing.googleblog.com/2013/03/testing-on-toilet-testing-state-vs.html +[tott-324]: https://testing.googleblog.com/2014/05/testing-on-toilet-effective-testing.html +[tott-329]: https://testing.googleblog.com/2014/05/testing-on-toilet-risk-driven-testing.html +[tott-350]: https://testing.googleblog.com/2015/01/testing-on-toilet-change-detector-tests.html **Additional External Writings**