Javascript Style Guide: Difference between revisions

From Proxmox VE
Jump to navigation Jump to search
(initial import, derived of the perl one)
 
No edit summary
 
(11 intermediate revisions by one other user not shown)
Line 9: Line 9:
Here's a summary of our style (which is somewhat unusual at least when it comes
Here's a summary of our style (which is somewhat unusual at least when it comes
to the mixed indentation).
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 ==
{| class="wikitable"
|-
! 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 ==
== Indentation ==
Line 34: Line 56:


The vim configuration would be <code>:set ts=8 sts=4 sw=4 noet</code>
The vim configuration would be <code>:set ts=8 sts=4 sw=4 noet</code>
== Variables ==
Code declaring new variables must '''not''' use <code>var</code>, but rather <code>let</code>, or if sensible <code>const</code>.
If you touch old code please transform any line you change also from the old <code>var</code> declaration to the modern ones with less side effects (e.g., function scope).
Avoid using <code>const</code> 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'' <code>var</code> 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 <code>if (cond) {</code>
* use <code>while (cond) {</code>
* '''not''' <code>if(cond) {</code>
* '''not''' <code>if (cond){</code>
* '''not''' <code>if(cond){</code>
'''BUT:''' no space between a ''function''`s name and its parameter list:
* <code>func(params)</code>
* '''not''' <code>func (params)</code>
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''' <code>if (cond) { return; }</code>
== 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 ==
== Breaking long lines and strings ==


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


Statements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information.
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 maximal line length tolerated for those exceptions is 100 columns.


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


We provide an eslint wrapper with our desired rule set backed in as default. You can install it from the [[Developer_Documentation#Development_Package_Repository|'devel' package repository]].
=== Installation ===
 
We provide an ESLint wrapper with our desired rule set backed in as default. You can install it easily after setting up the [[Developer_Documentation#Development_Package_Repository|'devel' package repository]]:
apt update
  apt install pve-eslint
  apt install pve-eslint
=== Basic Usage ===


Check specific files:
Check specific files:
Line 59: Line 137:
A great deal of errors or warnings can be automatically fixed:
A great deal of errors or warnings can be automatically fixed:
  eslint --fix .
  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/
[[Category:Development]]

Latest revision as of 11:04, 24 October 2023

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/