ceph-csi/docs/coding.md

# 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.

### Imports

We use the following convention for specifying imports:

```
<import standard library packages>

<import ceph-csi packages>

<import third-party packages>
```

Example:

```go
import (
 "os"
 "path"
 "strings"
 "time"

 "github.com/ceph/ceph-csi/internal/util"

 "github.com/pborman/uuid"
)
```

### 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

* 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.

### Mark Down Rules

* MD014 - Dollar signs used before commands without showing output

  The dollar signs are unnecessary, it is easier to copy and paste and
  less noisy if the dollar signs are omitted. Especially when the
  command doesn't list the output, but if the command follows output
  we can use '$ ' (dollar+space) mainly to differentiate between
  command and its ouput.

  scenario 1: when command doesn't follow output

  ```console
  cd ~/work
  ```

  scenario 2: when command follow output (use dollar+space)

  ```console
  $ ls ~/work
  file1 file2 dir1 dir2 ...
  ```