diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 01771f15b..13d852514 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58bd7e6ac..1acec13c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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