Standard for Public Code

Use a coherent style

Requirements

  • Contributions MUST adhere to a coding and/or writing style guide, either your own or an existing one that is advertised in or a 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
  • Unify vocabularies removing friction from communication between contributors

What this does not do

  • Help contributors write well or explain what they do well

How to test

  • Inspect wether the contributions are in line with the style guides as they are set out 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