Coding Style Guide

Coding Style Guide

In order to produce consistent, highly quality and readable code, our team follows certain coding styles and conventions. This document is a reflection of our team's commitment to continuous improvement. Please use this guide as a guidepost on how to keep the code reviews and the overall quality of code high.

General Formatting

Independent of any programming languages, we strive to make sure that all of our source code content can be utilized in both Windows, Mac and Unix, with an emphasis on Unix conventions.

Repository Files

In each of our repositories, we leverage the following tools in order to programatically enforce certain formatting and styles:

• .editorconfig - General coding styles for consistency across IDEs.
  • For Visual Studio Code users, you will need this extension
• .gitattributes - Force all text files to use Unix style line endings. This is necessary in order to prevent many headaches on Windows as we code for Unix platforms. Most of the time, this file will only contain the following line: * text=auto eol=lf

If you are starting out a new repository, one of the first few commits should address adding the above two files into source control as it will help ensure all developers are able to produce consistently styled code.

File Formatting

For all of our source code, please ensure that they adhere to the following guidelines:

• Unix style line endings - as that our deployment platform is Unix based, we want to ensure that all line endings use LF and not the Windows style CRLF ending. Make sure to check your git settings and have autocrlf = true or autocrlf = input (ref).
• Newline at end of source file - All file should have a newline at the end of source. This mainly prevents the \ No newline at end of file message from showing up in Git diffs. However, we also follow this style as that it makes whitespace changes at the end of a file much more succinct, and also prevents any chance of older legacy parsers from choking on file reads due to a lack of an ending newline.
• UTF-8 File encoding - Unless there exists a reason to do otherwise, all source code shall be formatted in UTF-8 character encoding.
• Use special characters inline - Unless there exists a reason to do otherwise, it is best to use the special non-ASCII character directly as part of the code as it improves readability (i.e. const units = 'μs'; vs const units = '\u03bcs';).

Logging

As with any application, there will usually be multiple levels of logging severity. With event logging, we attempt to conform to the syslog protocol as defined in RFC5424. Depending on the content that needs to be emitted, we suggest the following contexts in order of severity:

• error - Any code failures or exceptions
• warning - Any potentially concerning or unintended behaviors here
• info - Any general operation logging statements - Do NOT emit any potentially identifiable information and secrets at this level
• debug - Emit generalized debugging messages here - Avoid emitting any potentially identifiable information and secrets at this level
• verbose - Use this level for emitting any potentially sensitive information which aids with debugging
• silly / trace - If required, use this level for any function entry/exit tracing and anything else that would only be useful for fine-grained code behavior tracking

Whenever possible, when emitting logs, aim to ensure that the name of the function it is being emitted from is also a part of the log message. We suggest this convention as to ensure that we can more easily isolate any bugs or defects just from looking at the logs at a glance and know where to look next. For example, suppose you have a debug level statement coming from the generateDocument method. You would ideally want a log statement which looks similar to the following:

debug generateDocument generated filename abc_123__.docx

Languages

While the above guidelines apply to all types of source code, there are also additional conventions that we try to adhere to based on the language and framework being used.

Javascript

While there are plenty of Javascript style guidelines out there, we generally tend to loosely adhere to the Google Javascript Style Guide as that it generally aligns with most of the reasonable guidelines from ESLint recommended defaults. For our codebases in Javascript, we store our ESLint configurations as part of the package.json file.

Documentation

We generally emphasize the use of JSDoc to annotate our code. This has the added benefit of allowing certain IDEs to immediately pick up on things such as code descriptions, parameters, return values, errors, and more upon hover-over, which can help other developers when they use our codebase. Each function should have an attached JSDoc to describe its function and purpose.

Formatting

In general, the Google style guide on formatting here provides a very good framework of the type of code style we would expect in the source code. Key things of note are the following:

• Use braces for all control structures
• 2 spaces for indentation
• Prefer using functional expressions (i.e. (arg1, arg2) => { code stuff... })
• Indent 2 spaces for switch statements
• Semicolons are required at end of statement
• Attempt to limit lines to 80 characters

Generally we will want to let our IDE's formatter handle the formatting as the .editorconfig file will express the desired formatting style.

Node.js

React

Vue

YAML

OpenShift

Groovy

PostgreSQL