Merge pull request #1980 from SUSE/pr-checkbox-godocs

PR template: Add godoc comments to checklist
This commit is contained in:
Travis Nielsen authored and GitHub committed 2018-08-14 15:35:03 -06:00
commit d87f9c4a4e
2 files changed
+18

No files matched your search

+1
View File
@@ -13,3 +13,4 @@ Resolves #
- [ ] Upgrade from previous release is tested and upgrade user guide is updated, if necessary.
- [ ] Code generation (`make codegen`) has been run to update object specifications, if necessary.
- [ ] `make vendor` does not cause changes.
- [ ] Comments have been added or updated based on the standards set in [CONTRIBUTING.md](../blob/master/CONTRIBUTING.md#comments)
+17
View File
@@ -62,6 +62,23 @@ For detailed contribution instructions, refer to the [development flow](Document
Rook projects are written in golang and follows the style guidelines dictated by
the go fmt as well as go vet tools.
## Comments
Comments should be added to all new methods and structures as is appropriate for the coding
language. Additionally, if an existing method or structure is modified sufficiently, comments should
be created if they do not yet exist and updated if they do.
The goal of comments is to make the code more readable and grokkable by future developers. Once you
have made your code as understandable as possible, add comments to make sure future developers can
understand (A) what this piece of code's responsibility is within Rook's architecture and (B) why it
was written as it was.
The below blog entry explains more the why's and how's of this guideline.
https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/
For Go, Rook follows standard godoc guidelines.
A concise godoc guideline can be found here: https://blog.golang.org/godoc-documenting-go-code
## Commit Messages
We follow a rough convention for commit messages that is designed to answer two