From 4fdbdeb54213281ec3b51a87e5183e25c2876bda Mon Sep 17 00:00:00 2001 From: Blaine Gardner Date: Thu, 2 Aug 2018 07:03:25 -0600 Subject: [PATCH] PR template: Add godoc comments to checklist We want to have good code documentation in the future, and we would like to slowly develop better documentation for existing code. As a checklist item for PRs, add a requirement for godoc-style comments when (1) new code items are added and (2) when existing items are sufficiently modified. Signed-off-by: Blaine Gardner --- .github/PULL_REQUEST_TEMPLATE.md | 1 + CONTRIBUTING.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) 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 e1da85f91..2ad331ac4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,6 +55,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