diff --git a/docs/coding.md b/docs/coding.md new file mode 100644 index 000000000..2547724a3 --- /dev/null +++ b/docs/coding.md @@ -0,0 +1,77 @@ +# Coding Conventions + +Please follow coding conventions and guidelines described in the following documents: + +* [Go proverbs](https://go-proverbs.github.io/) - highly recommended read +* [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments) +* [Effective Go](https://golang.org/doc/effective_go.html) +* [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) + +Here's a list of some more specific conventions that are often followed in +the code and will be pointed out in the review process: + +### General +* Keep variable names short for variables that are local to the function. +* Do not export a function or variable name outside the package until you + have an external consumer for it. +* Have setter or getter interfaces/methods to access/manipulate information in + a different package. +* Do not use named return values in function definitions. Use only the type. + Exception: defer()'d functions. + +### Imports + +We use the following convention for specifying imports: + +``` + + + + + +``` + +Example: + +```go +import ( + "os" + "path" + "strings" + "time" + + "github.com/ceph/ceph-csi/pkg/util" + + "github.com/pborman/uuid" + "github.com/pkg/errors" + +) +``` + +### Error Handling + +* Use variable name `err` to denote error variable during a function call. +* Reuse the previously declared `err` variable as long as it is in scope. + For example, do not use `errWrite` or `errRead`. +* Do not panic() for errors that can be bubbled up back to user. Use panic() + only for fatal errors which shouldn't occur. +* Do not ignore errors using `_` variable unless you know what you're doing. +* Error strings should not start with a capital letter. +* If error requires passing of extra information, you can define a new type +* Error types should end with `Error`. + +### Logging + +* If a function is only invoked as part of a transaction step, always use the + transaction's logger to ensure propagation of request ID and transaction ID. +* The inner-most utility functions should never log. Logging must almost always + be done by the caller on receiving an `error`. +* Always use log level `DEBUG` to provide useful **diagnostic information** to + developers or sysadmins. +* Use log level `INFO` to provide information to users or sysadmins. This is the + kind of information you'd like to log in an out-of-the-box configuration in + happy scenario. +* Use log level `WARN` when something fails but there's a workaround or fallback + or retry for it and/or is fully recoverable. +* Use log level `ERROR` when something occurs which is fatal to the operation, + but not to the service or application.