Javascript Style Guide

Proxmox Javascript Style Guide

Various of our files have inconsistent styles due to historical growth as well as because of the mixed styles we got from various contributors.

Please try to follow this guide if you're working on code for Proxmox projects to avoid adding to the style mess.

Here's a summary of our style (which is somewhat unusual at least when it comes to the mixed indentation).

Target Browsers

Proxmox web-interfaces try to support most widely used browsers in their current version, concretely: Chrome (Chromium), Firefox (also ESR), Safari, Edge.

Browser-specific workarounds or features should be avoided, any exception will be decided on a case-by-case basis.

Target ECMAScript Version

Debian Base Release	ECMAScript Version
<= Stretch	ES5
Buster	ES 2018
Bullseye	ES 2020

See https://kangax.github.io/compat-table/es2016plus/ for available features.

Indentation

We indent by 4 spaces, assume tabs to be 8 spaces and convert all groups of 8 spaces into tabs at the beginning of a line. Here's an example, with tabs represented via '>........'

function foo(arg1, arg2, arg3) {
    if (arg1) {
>.......console.log(arg2);
>.......if (arg3) {
>.......    if (arg3 !== arg2) {
>.......>.......throw "Exceptions should avoided for dynamic stuff";
>.......    }
>.......}
    }
}

Like all editors for some reason I'll never understand we do not distinguish between indentation and alignment, so if you split up an expression over multiple lines we still use the same "all 8 spaces are 1 tab" pattern.

The vim configuration would be :set ts=8 sts=4 sw=4 noet

Variables

Code declaring new variables must not use var, but rather let, or if sensible const.

If you touch old code please transform any line you change also from the old var declaration to the modern ones with less side effects (e.g., function scope).

Avoid using const for everything, but rather in the sense of constants. JavaScript is to dynamic for it to provide actual benefits if used as default.

An exception is copying over code from ExtJS to override a specific component, there you can keep existing var usage so that the unmodified code stays closer to the original. Adding comments indicating boiundaries between changed and original code is recommended.

Spacing and Syntax Usage

Spaces around parenthesis with syntactical words are inserted as you would in regular text (one before the opening parenthesis, one after the closing parenthesis). Similarly, for curly braces:

• use if (cond) {
• use while (cond) {
• not if(cond) {
• not if (cond){
• not if(cond){

BUT: no space between a function`s name and its parameter list:

• func(params)
• not func (params)

You can condense short comments on the if-statement's clause inner body line as long as text-width limits are upheld:

 if (cond) { // comment here that we early exit because XYZ
     return; // could be also comment here, depends on the comment reason
 }

Single-Line If-Statement

In general, avoid single line if statements for new/changed code:

• use

 if (cond) {
     return;
 }

• not if (cond) { return; }

Casing

While there are quite some existing uses of snake_case, you should use camelCase for (new) variable and function names.

Breaking long lines and strings

The preferred limit on the length of a single line is 100 columns.

Statements longer than 80 columns may benefit readability if broken into sensible chunks, but often exceeding 80 columns avoids line-bloat or significantly increases readability while not hiding information. The maximal line length tolerated for those exceptions is 100 columns.

The vim configuration would be :set cc=81 or, to show both soft and hard limit: :set cc=81,101

Linting

Instead of describing various rules and examples to follow the used coding and formatting style, it's quicker to just use eslint.

Installation

We provide an ESLint wrapper with our desired rule set backed in as default. You can install it easily after setting up the 'devel' package repository:

apt update
apt install pve-eslint

Basic Usage

Check specific files:

eslint src/Utils.js

Check all .js files from this and child directories:

eslint .

A great deal of errors or warnings can be automatically fixed:

eslint --fix .

Rule Information

For errors and warnings ESLint will show a shorter rule ID and a longer human-readable string.

You can use the rule ID to search the ESLint documentation, to get more information about a specific rule: https://eslint.org/docs/rules/