Software contribution and development guide

Style guides

The common baseline standard is: Write code for humans to read.

You are free to format your code incorrectly, but don’t expect support or sympathy if you find that you cry yourself to sleep every night as a result.

— Tom Grydeland

Programs must be written for people to read, and only incidentally for machines to execute.

— Harold Abelson

General

Never use these characters as single character variable names:

l (lowercase letter L)
O (uppercase letter o)
I (uppercase letter i)

In some fonts, these characters are indistinguishable from the numerals one and zero. When tempted to use l, use L instead.

You could consider placing a .editorconfig file into your repository to define the coding style and related editor configuration. See editorconfig.org for more details.

Python

C

Javascript / HTML / CSS

Install prettier for your IDE and run it in ci/cd. Exclusions are set in .prettierignore.

prettier:
  stage: test
  script:    
    # fails the job if prettier thinks any files need to change
    - ./node_modules/.bin/prettier --list-different src

Bash

Avoid when possible. But when used, at least use shellcheck and shfmt with these settings:

-ci: Switch cases are indented
-i 2: Indentation 2 spaces (not tabs as default)

Add the following jobs to .gitlab-ci.yml to stop builds that don’t follow the rules. Both assume your bash scripts are in the root dir, so change the paths accordingly.

shellcheck:
  image: koalaman/shellcheck-alpine:stable
  stage: test
  script:
    - shellcheck *.sh

shellformat:
  image: mvdan/shfmt:v3.2.0-alpine
  stage: test
  script:    
    - shfmt -i 2 -ci *.sh

Rust

We aim to follow the style-guide information already available in the Rust documentation: