ceph-csi/docs/coding.md

Coding Conventions

Please follow coding conventions and guidelines described in the following documents:

• Go proverbs - highly recommended read
• CodeReviewComments
• Effective Go
• How to Write a Git Commit Message

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:

<import standard library packages>

<import ceph packages>

<import third-party packages>

Example:

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.