The goal of this document is to describe how Beeper writes Go code. This includes code style, library choices, and other important guidelines.

Style

The following style guidelines are meant to supplement existing style guides and to add additional emphasis on certain rules that are especially important for Beeper and elaborate on some rules that only apply to us.

Base style guides:

• https://go.dev/doc/effective_go
• https://github.com/golang/go/wiki/CodeReviewComments

General

• Use any instead of interface{}.
• Map iteration order is randomized, so slices are better when there's any chance of the order mattering (like HTTP routes).
• http.StatusX constants should always be used for status codes, don't write the raw code anywhere.

Variables

• Variables should be lowerCamelCase.
• Use consistent casing for initialisms (https://github.com/golang/go/wiki/CodeReviewComments#initialisms)
• Prefer var x type over x := type{} for zero-value initializations.

Control Flow

• Unnecessary nesting should be avoided. When handling errors or different cases, nest small blocks and don't nest the rest. In general, the “small block” should be the error handling case. (https://github.com/golang/go/wiki/CodeReviewComments#indent-error-flow)

A corollary is that reading the left-aligned code should describe the happy-path.

```go
// do this
func stuff() error {
    err := couldError()
    if err != nil {
        return err
    }
    doThing()
    doOtherThing()
    doAnotherThing()
    return nil
}

// not this
func stuff(thing bool) error {
    err := couldError()
    if err == nil {
        doThing()
        doOtherThing()
        doAnotherThing()
    }
    return err
}
```

- **Exception:** if there are multiple different conditions, and all of the blocks are short (a few lines), an `if` chain can be nicer. This is especially nice if all the conditions would need a `return` normally.
    
    ```go
    package main
    
    func erroringThing() (err error) {
      if err = stuff1(); err != nil {
        err = fmt.Errorf("failed to do thing #1: %w", err)
      } else if err = stuff2(); err != nil {
        err = fmt.Errorf("failed to do thing #2: %w", err)
      } else {
        fmt.Println("Success")
      }
      // implicitly return err
      return
    }
    
    ```

Pre-Commit Hooks

The following pre-commit configuration should be used (replace YOURSERV with the name of your module). Run pre-commit autoupgrade to get the latest versions.

• Sample pre-commit-config.yaml file:

Databases