cookbook

Source code conventions

Adhere to these general source code conventions unless otherwise specified in language specific guide.

Files

Use language specific indentation.
If you have to use tabs, do not mix tabs and spaces in a single project.
All files end with an empty line.
Use lint for specific language if available.
Limit line length to 80 characters
Strive for readable code. Imagine writing code for your past self when you were in 1st year college trying to read code for the first time.
Use descriptive variable names
Prefer short well named methods with few parameters. If a function doesn’t fit in its entirety on the screen in a normal IDE at a normal font size then you need a pretty darn good reason as to why not. Decompose as necessary.
Avoid obvious comments e.g.

// get the country code
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);

// if country code is US
if ($country_code == 'US') {

  // display the form input for state
  echo form_input_state();
}

Group code into logical blocks e.g.

func main() {

    // To start, here's how to dump a string (or just
    // bytes) into a file.
    d1 := []byte("hello\ngo\n")
    err := ioutil.WriteFile("/tmp/dat1", d1, 0644)
    check(err)

    // For more granular writes, open a file for writing.
    f, err := os.Create("/tmp/dat2")
    check(err)

    // It's idiomatic to defer a `Close` immediately
    // after opening a file.
    defer f.Close()

    // You can `Write` byte slices as you'd expect.
    d2 := []byte{115, 111, 109, 101, 10}
    n2, err := f.Write(d2)
    check(err)
    fmt.Printf("wrote %d bytes\n", n2)

    // A `WriteString` is also available.
    n3, err := f.WriteString("writes\n")
    fmt.Printf("wrote %d bytes\n", n3)

    // Issue a `Sync` to flush writes to stable storage.
    f.Sync()

    // `bufio` provides buffered writers in addition
    // to the buffered readers we saw earlier.
    w := bufio.NewWriter(f)
    n4, err := w.WriteString("buffered\n")
    fmt.Printf("wrote %d bytes\n", n4)

    // Use `Flush` to ensure all buffered operations have
    // been applied to the underlying writer.
    w.Flush()
}

Try to follow the DRY principle. Never Cut and Paste Within a Project

“Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.”

cookbook

Source code conventions

Files

Recommended reading