Generic Coding Standards

These are generic coding standards for the project

Each repository may contain a Readme.md which may contain a more specific statement of the coding conventions for that specific repository, with language-specific and domain-specific requirements.

For Reviewers

These “generic” standards may seem like common sense, but following the spirit of them is very important for the success of the project. When in doubt, press that the developer actually considered these places, and get positive affirmation that these rules are being followed to the best of their ability.

Common Sense

>Be wary of abnormal data structures and program flows.

Example:

switch(String s){

case “a”:
case “b”: System.exit(1);
}

>Be wary of [IDE/linter] warnings and errors. Simple warnings can hide more complex errors.

When ‘ignoring’ errors, always seek to ignore the smallest set of the class of error that hits all the relevant cases. It’s always helpful to comment your rationale for being ‘smarter than the compiler’.

Readability/Maintenance

>Cases and variable names should be sensible.

The easiest way to measure this yardstick is with code review and commentary.

>Classes/code subdivisions should exist where they make logical sense.

>Commits and PRs should have a logical scope

PRs should have this summarized in the name, expounded on in the body, and linked to the appropriate design/requirement/task documents.

Interfaces

Outside interfaces need comments explaining all inputs and outputs, as well as a general description of its function.

Example:

For repo owners and toolchain managers

Look into tools to spot errors/exceptions

Try to force standards using the tools [spaces vs. tabs]

Make sure your Readme.md is up to date, and contains suggestions on IDEs