Code Conventions

Code Conventions#

  • Baseline

  • Go

    • Functions should be short and call out to other short functions

    • Choose verbose, descriptive, human-readable names (handler not hdlr, handleFunctionAdd not add). The only exception is with receivers (func (c *Client) foo())

    • Insert newlines before comments and after blocks of code (e.g., a non-nested } within a function)

    • Functionality and state must be contained within instantiatable objects. Package level state variables are discouraged

    • Within a struct, exported methods go first, followed by non-exported methods. This holds true to methods conceptually belonging to a struct (e.g., “static” methods without receivers)

    • Follow the below convention for file-related variables (this has been known to save lives):

      • somethingFileName: The name of a file, without its location. e.g., example.go

      • somethingDir: The location of a directory. e.g., /a/b/c

      • somethingPath: The full location of a resource, which can be either a file or directory (e.g., /a/b/c or /a/b/c/example.go). If the resource can only be a dir, use somethingDir

      • somethingFile: The file object of something

      • somethingFileContents: The result of reading the file, i.e., with ReadAll

    • Put variable args at the end of error and log messages. This keeps the static prefix consistent, making it easy to grep in logs and code

      • errors.Wrapf(err, "Failed to read auth config for function %s", functionName) ✓

      • errors.Wrapf(err, "Failed to read function %s auth config", functionName) ✗

  • Testing

    • Use testify and testify suites (see existing examples)

    • Assert with suite.Require().<assertion>

    • Function order within a test suite should be:

      • Suite struct declaration

      • SetupSuite (if applicable)

      • SetupTest (if applicable)

      • TearDownTest (if applicable)

      • TearDownSuite (if applicable)

      • Tests

      • Unexported helpers