Overview

NML want everybody to have the freedom they need to creatively contribute to their work. Too many rules stifle creative freedom and too few entices disorder and confusion. The document outlines some practices and standards that are highly encouraged and, where noted with expected.

Feel free to raise your opinion on any of these guidelines and to contribute to the document. Email Charl, Justin, Isobel, or Kirsten with any corrections or suggestions.

Coding

General

• When you touch code you are already introducing risk. Improve any non-conforming standards and practices as part of your changes to the code. !Expected!
• Readability is more important than performance or cool logic in almost all code NML would write for our clients. All exceptions should be clearly motivated with a comment that passes PR review. !Expected!
• TODO comments are only acceptable if it references a work item number and description as part of the comment !Expected!
• Don't leave commented out code in the codebase. !Expected!
• Use tools like Prettier, Rider, Resharper, Stylecop. It is acceptable to decide and agree on which tools and how stringent configuration should be on a per-project basis.

Git

• Name branches in a way that makes them easily identifiable and correlatable to work items or stories. A good format is <source-branch>.<story-number>.<description>

  • for example: main.12345.AddAdditionsFormValidation

• Use the Karma commit message format for commits and pull request names `!Expected!

  • Git Commit Msg

• Squash commit Pull Requests. !Expected!

• When commenting on a pull request follow the following convention !Expected!

  1. Clearly explain what is wrong.
  2. Clearly motivate your assertion. Provide references if possible.
  3. Optionally provide a solution. Leave pseudo code or a clear description of how the problem can be resolved

C#

The following links are the basis for NML C# coding practices. Any NML practices that conflict with or are additional to these guidelines are noted below.

C# Coding Conventions

C# Coding Style

Secure coding guidelines

NML conflicts & additions

General

• Don't ignore warnings on syntax and naming from Rider or ReSharper. If you don't understand or are unsure of why you are getting a warning or suggestion, take the time to read up about it. You cannot just assume the suggestion is correct when it comes to things like nullable reference types.

• Methods or properties that are declared as public static is a code smell and should be avoided

  • Except for extension methods

• Classes that are declared as public static is a code smell that should only be used for holding constants of static values

  • Except for extension method classes

• Member fields should always be private. Use properties if external access is required.

• Prefer the discard (_) character when a parameter isn't needed.

Naming

• Prefixing private static and thread static fields with s_ and t_ is optional. NML has used just _ for a very long time and it is better to follow the accepted team standard on existing projects
• Avoid single character or acronym variable names unless it can be argued that that the acronym is common and easily understood by anybody. Otp, Vat, Usd, Eng can be argued to be common acronyms.
• Avoid single character or acronym variable names for loops and lambdas.

      for (var index = 0; index < input.Length; index++)
      {
          // Use index
      }

• Generic types should prefixed with T and properly named. Don't T, U, V, etc. Example TSource. !Expected!

Layout Conventions

• Prefer local functions to parentheses to make clauses in an expression apparent

	if ((val1 > val2) && (val1 <= val3))
	{
	    // Take appropriate action.
	}
	Should be:
	if (IsVal1GreaterThanVal2() && IsVal1GreaterThanVal3())
	{
	    // Take appropriate action.
	}

Implicitly typed local variables

• Use var. You almost never actually need to know the type of a variable. Using type names for declaration is just noise to readability.
• Use var in for and foreach except where the explicit type is a must, for example, Regex matches and collections

LINQ Queries

• Use LINQ method chains instead of LINQ query syntax

TypeScript

The following link is the basis for NML TypeScript coding practices. Any NML practices that conflict with or are additional to these guidelines are noted below.

Google TypeScript Style Guide

Conflicts or additions

• Don't leave 'console.log' in commits
• Prefer the discard (_) character when a parameter isn't needed.

React

The following link is the basis for NML React coding practices. Any NML practices that conflict with or are additional to these guidelines are noted below.

Airbnb React/JSX Style Guide https://css-tricks.com/react-code-style-guide/