vbatts/registry
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Revise coding style guidelines from Docker project commentary

Browse source 
Signed-off-by: Stephen J Day <stephen.day@docker.com>
This commit is contained in:
Stephen J Day 2015-07-21 13:48:43 -07:00
parent 856638e299
commit ab972d9598
1 changed files with 16 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
CONTRIBUTING.md
View file

@ -97,32 +97,41 @@ 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 3. All code should follow the guidelines covered in [Effective
https://github.com/golang/go/wiki/CodeReviewComments. 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. 6. Variable name length should be proportional to its context and no longer.
noALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo. In `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`.
practice, short methods will have short variable names and globals will 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. No, we don't need another unit testing framework.
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.