Introduction

We describe a set of standards for code. We also explain our reasoning for these choices. We want this to act as a living document of our practices for current, and future, contributors to the project. We also intend this document to evolve as our needs change, as well as act as a single point of truth for standards.

Changelog

Motivation

Conventions

The words MUST, SHOULD, MUST NOT, SHOULD NOT and MAY are defined as per RFC 2119. Specifically:

• MUST, as well as its synonyms REQUIRED or SHALL, describe an absolute requirement.
• MUST NOT, as well as its synonym SHALL NOT, describe an absolute prohibition.
• SHOULD, as well as the adjective RECOMMENDED, describe an ‘ideal-world’ requirement. Unless there exist specific reasons not to follow this requirement, it should be followed, and going against this requirement should be understood and carefully weighed in its consequences.
• SHOULD NOT, as well as its synonym NOT RECOMMENDED, describe an ‘ideal-world’ prohibition, with similar caveats to SHOULD.
• MAY, as well as the adjective OPTIONAL, describe a ‘take-it-or-leave-it’ situation; it can be followed, or not, and neither is given preference.

Tools

Compiler warning settings

The following warnings MUST be enabled for all builds of any project, in the ghc-options of the Cabal file:

• -Wall
• -Wcompat
• -Wincomplete-uni-patterns
• -Wincomplete-record-updates
• -Wmissing-export-lists