mirror of https://github.com/google/styleguide
Merge branch 'gh-pages' into patch-1
ujihisa
GitHub
commit
54aad34238
|
|
@ -7,3 +7,4 @@ lispguide.xml @sfreilich
|
|||
pyguide.md @gpshead
|
||||
pylintrc @gpshead
|
||||
shellguide.md @dimo414 @eatnumber1 @vapier
|
||||
/go/ @carrotman42 @gaal @matttproud
|
||||
|
|
|
|||
74
README.md
74
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.
|
||||
|
||||
<a rel="license" href="https://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/88x31.png" /></a>
|
||||
|
||||
|
|
@ -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/
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
<a id="mixed-caps"></a>
|
||||
|
||||
* **Formatting**: see https://google.github.io/styleguide/go/guide#formatting
|
||||
* **Formatting**: see [guide#formatting](guide#formatting)
|
||||
<a id="formatting"></a>
|
||||
|
||||
* **Line Length**: see
|
||||
https://google.github.io/styleguide/go/guide#line-length
|
||||
* **Line Length**: see [guide#line-length](guide#line-length)
|
||||
<a id="line-length"></a>
|
||||
|
||||
<a id="naming"></a>
|
||||
|
|
@ -116,7 +115,7 @@ wherever possible for consistency.
|
|||
|
||||
<!--#include file="/go/g3doc/style/includes/special-name-exception.md"-->
|
||||
|
||||
See also: https://go.dev/blog/package-names
|
||||
See also: [Go blog post about package names](https://go.dev/blog/package-names).
|
||||
|
||||
<a id="receiver-names"></a>
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
22
go/index.md
22
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**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue