diff options
| -rw-r--r-- | CONTRIBUTING.md | 8 | ||||
| -rw-r--r-- | g3doc/style.md | 88 |
2 files changed, 90 insertions, 6 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f8f4c985..89180eb3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,10 +37,8 @@ Dependencies can be added by using `go mod get`. In order to keep the ### Coding Guidelines -All Go code should conform to the [Go style guidelines][gostyle]. C++ code -should conform to the [Google C++ Style Guide][cppstyle] and the guidelines -described for tests. Note that code may be automatically formatted per the -guidelines when merged. +All code should comply with the [style guide](g3doc/style.md). Note that code +may be automatically formatted per the guidelines when merged. As a secure runtime, we need to maintain the safety of all of code included in gVisor. The following rules help mitigate issues. @@ -125,9 +123,7 @@ Contributions made by corporations are covered by a different agreement than the one above, the [Software Grant and Corporate Contributor License Agreement][gccla]. -[cppstyle]: https://google.github.io/styleguide/cppguide.html [gcla]: https://cla.developers.google.com/about/google-individual [gccla]: https://cla.developers.google.com/about/google-corporate [github]: https://github.com/google/gvisor/compare [gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev -[gostyle]: https://github.com/golang/go/wiki/CodeReviewComments diff --git a/g3doc/style.md b/g3doc/style.md new file mode 100644 index 000000000..d10549fe9 --- /dev/null +++ b/g3doc/style.md @@ -0,0 +1,88 @@ +# Provisional style guide + +> These guidelines are new and may change. This note will be removed when +> consensus is reached. + +Not all existing code will comply with this style guide, but new code should. +Further, it is a goal to eventually update all existing code to be in +compliance. + +## All code + +### Early exit + +All code, unless it substantially increases the line count or complexity, should +use early exits from loops and functions where possible. + +## Go specific + +All Go code should comply with the [Go Code Review Comments][gostyle] and +[Effective Go][effective_go] guides, as well as the additional guidelines +described below. + +### Mutexes + +#### Naming + +Mutexes should be named mu or xxxMu. Mutexes as a general rule should not be +exported. Instead, export methods which use the mutexes to avoid leaky +abstractions. + +#### Location + +Mutexes should be sibling fields to the fields that they protect. Mutexes should +not be declared as global variables, instead use a struct (anonymous ok, but +naming conventions still apply). + +Mutexes should be ordered before the fields that they protect. + +#### Comments + +Mutexes should have a comment on their declaration explaining any ordering +requirements (or pointing to where this information can be found), if +applicable. There is no need for a comment explaining which fields are +protected. + +Each field or variable protected by a mutex should state as such in a comment on +the field or variable declaration. + +### Unused returns + +Unused returns should be explicitly ignored with underscores. If there is a +function which is commonly used without using its return(s), a wrapper function +should be declared which explicitly ignores the returns. That said, in many +cases, it may make sense for the wrapper to check the returns. + +### Formatting verbs + +Built-in types should use their associated verbs (e.g. %d for integral types), +but other types should use a %v variant, even if they implement fmt.Stringer. +The built-in `error` type should use %w when formatted with `fmt.Errorf`, but +only then. + +### Wrapping + +Comments should be wrapped at 80 columns with a 2 space tab size. + +Code does not need to be wrapped, but if wrapping would make it more readable, +it should be wrapped with each subcomponent of the thing being wrapped on its +own line. For example, if a struct is split between lines, each field should be +on its own line. + +#### Example + +```go +_ = exec.Cmd{ + Path: "/foo/bar", + Args: []string{"-baz"}, +} +``` + +## C++ specific + +C++ code should conform to the [Google C++ Style Guide][cppstyle] and the +guidelines described for tests. + +[cppstyle]: https://google.github.io/styleguide/cppguide.html +[gostyle]: https://github.com/golang/go/wiki/CodeReviewComments +[effective_go]: https://golang.org/doc/effective_go.html |