|
|
@@ -234,6 +234,8 @@ close an issue. Including references automatically closes the issue on a merge.
|
|
|
Please do not add yourself to the `AUTHORS` file, as it is regenerated regularly
|
|
|
from the Git history.
|
|
|
|
|
|
+Please see the [Coding Style](#coding-style) for further guidelines.
|
|
|
+
|
|
|
### Merge approval
|
|
|
|
|
|
Docker maintainers use LGTM (Looks Good To Me) in comments on the code review to
|
|
|
@@ -385,3 +387,49 @@ do need a fair way to deal with people who are making our community suck.
|
|
|
appeals, we know that mistakes happen, and we'll work with you to come up with a
|
|
|
fair solution if there has been a misunderstanding.
|
|
|
|
|
|
+## Coding Style
|
|
|
+
|
|
|
+Unless explicitly stated, we follow all coding guidelines from the Go
|
|
|
+community. While some of these standards may seem arbitrary, they somehow seem
|
|
|
+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:
|
|
|
+
|
|
|
+1. All code should be formatted with `gofmt -s`.
|
|
|
+2. All code should pass the default levels of
|
|
|
+ [`golint`](https://github.com/golang/lint).
|
|
|
+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.
|
|
|
+5. Document _all_ declarations and methods, even private ones. Declare
|
|
|
+ expectations, caveats and anything else that may be important. If a type
|
|
|
+ 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.
|
|
|
+ `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`.
|
|
|
+ In practice, short methods will have short variable names and globals will
|
|
|
+ have longer names.
|
|
|
+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
|
|
|
+ compound name, lose the underscore.
|
|
|
+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
|
|
|
+ part of a util package. Just leave it unexported and well-documented.
|
|
|
+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
|
|
|
+ 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
|
|
|
+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
|
|
|
+kool-aid is a lot easier than going thirsty.
|
Sebastiaan van Stijn