|
@@ -97,32 +97,43 @@ Unless explicitly stated, we follow all coding guidelines from the Go
|
|
community. While some of these standards may seem arbitrary, they somehow seem
|
|
community. While some of these standards may seem arbitrary, they somehow seem
|
|
to result in a solid, consistent codebase.
|
|
to result in a solid, consistent codebase.
|
|
|
|
|
|
|
|
+It is possible that the code base does not currently comply with these
|
|
|
|
+guidelines. We are not looking for a massive PR that fixes this, since that
|
|
|
|
+goes against the spirit of the guidelines. All new contributions should make a
|
|
|
|
+best effort to clean up and make the code base better than they left it.
|
|
|
|
+Obviously, apply your best judgement. Remember, the goal here is to make the
|
|
|
|
+code base easier for humans to navigate and understand. Always keep that in
|
|
|
|
+mind when nudging others to comply.
|
|
|
|
+
|
|
The rules:
|
|
The rules:
|
|
|
|
|
|
1. All code should be formatted with `gofmt -s`.
|
|
1. All code should be formatted with `gofmt -s`.
|
|
2. All code should pass the default levels of
|
|
2. All code should pass the default levels of
|
|
[`golint`](https://github.com/golang/lint).
|
|
[`golint`](https://github.com/golang/lint).
|
|
-3. All code should follow the guidelines covered at
|
|
|
|
- https://github.com/golang/go/wiki/CodeReviewComments.
|
|
|
|
|
|
+3. All code should follow the guidelines covered in [Effective
|
|
|
|
+ Go](http://golang.org/doc/effective_go.html) and [Go Code Review
|
|
|
|
+ Comments](https://github.com/golang/go/wiki/CodeReviewComments).
|
|
4. Comment the code. Tell us the why, the history and the context.
|
|
4. Comment the code. Tell us the why, the history and the context.
|
|
5. Document _all_ declarations and methods, even private ones. Declare
|
|
5. Document _all_ declarations and methods, even private ones. Declare
|
|
expectations, caveats and anything else that may be important. If a type
|
|
expectations, caveats and anything else that may be important. If a type
|
|
gets exported, having the comments already there will ensure it's ready.
|
|
gets exported, having the comments already there will ensure it's ready.
|
|
-6. Variable name length should be proportional to it's context and no longer.
|
|
|
|
- noALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo. In
|
|
|
|
- practice, short methods will have short variable names and globals will
|
|
|
|
|
|
+6. Variable name length should be proportional to its context and no longer.
|
|
|
|
+ `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`.
|
|
|
|
+ In practice, short methods will have short variable names and globals will
|
|
have longer names.
|
|
have longer names.
|
|
7. No underscores in package names. If you need a compound name, step back,
|
|
7. No underscores in package names. If you need a compound name, step back,
|
|
and re-examine why you need a compound name. If you still think you need a
|
|
and re-examine why you need a compound name. If you still think you need a
|
|
compound name, lose the underscore.
|
|
compound name, lose the underscore.
|
|
8. No utils or helpers packages. If a function is not general enough to
|
|
8. No utils or helpers packages. If a function is not general enough to
|
|
- warrant it's own package, it has not been written generally enough to be a
|
|
|
|
|
|
+ warrant its own package, it has not been written generally enough to be a
|
|
part of a util package. Just leave it unexported and well-documented.
|
|
part of a util package. Just leave it unexported and well-documented.
|
|
-9. No, we don't need another unit testing framework.
|
|
|
|
|
|
+9. All tests should run with `go test` and outside tooling should not be
|
|
|
|
+ required. No, we don't need another unit testing framework. Assertion
|
|
|
|
+ packages are acceptable if they provide _real_ incremental value.
|
|
10. Even though we call these "rules" above, they are actually just
|
|
10. Even though we call these "rules" above, they are actually just
|
|
guidelines. Since you've read all the rules, you now know that.
|
|
guidelines. Since you've read all the rules, you now know that.
|
|
|
|
|
|
If you are having trouble getting into the mood of idiomatic Go, we recommend
|
|
If you are having trouble getting into the mood of idiomatic Go, we recommend
|
|
-reading through [`Effective Go`](http://golang.org/doc/effective_go.html). The
|
|
|
|
|
|
+reading through [Effective Go](http://golang.org/doc/effective_go.html). The
|
|
[Go Blog](http://blog.golang.org/) is also a great resource. Drinking the
|
|
[Go Blog](http://blog.golang.org/) is also a great resource. Drinking the
|
|
kool-aid is a lot easier than going thirsty.
|
|
kool-aid is a lot easier than going thirsty.
|