Standard for Public Code

Use a coherent style

Requirements

  • Contributions MUST adhere to either a coding or writing style guide, either your own or an existing one that is advertised in or part of the codebase.
  • Contributions SHOULD pass automated tests on style.
  • Your codebase SHOULD include inline comments and documentation for non-trivial sections.
  • You MAY include sections in your style guide on understandable English.

Why this is important

  • Enables contributors in different environments to work together on a unified product.
  • Unifying vocabularies reduces friction in communication between contributors.

What this does not do

  • Help contributors write well or effectively explain what they do.

How to test

  • Inspect whether contributions are in line with the style guides specified in the documentation.

Policy makers: what you need to do

  • Create, follow and continually improve on a style guide for policy and documentation as well as document this in the codebase, for example in the CONTRIBUTING or README.

Management: what you need to do

  • Include written language, source, test and policy standards in your organizational definition of quality.

Developers and designers: what you need to do

  • Create, follow and continually improve on a style guide for source, tests and documentation as well as document this in the codebase, for example in the CONTRIBUTING or README.
  • Use a linter.
  • Add linter configurations to the codebase.

Further reading