Javascript Coding Guidelines

JavaScript Coding Guidelines

When to Use

Load this skill when asked to:

• Create or update .js files or inline JavaScript in HTML.
• Modernize legacy JavaScript to current ECMAScript patterns.
• Review JavaScript for readability, maintainability, safety, and standards alignment.
• Replace outdated async, DOM, array, object, string, or control-flow patterns.

Core Principles

• Prefer standardized ECMAScript and Web APIs over deprecated, prefixed, or ad-hoc patterns.
• Optimize for readability first: short, semantic names and direct control flow.
• Use modern syntax when the target runtime supports it; do not introduce shiny syntax that the runtime cannot execute.
• Keep code compact and focused; add comments only when intent is not obvious.
• Avoid hidden behavior, broad fallbacks, and overly clever coercions.

Default Rules

Variables and naming

• Use const by default and let only when reassignment is required.
• Do not use var.
• Declare one variable per line.
• Use camelCase for variables, functions, properties, and methods.
• Use PascalCase for classes.
• Use short, semantic names; avoid non-obvious abbreviations, Hungarian notation, and type suffixes/prefixes.
• Name collections by content in plural form (plugins, icons, users), not by container type (pluginList, iconArray).

Functions and methods

• Prefer function declarations for named functions.
• Use arrow functions for callbacks that do not need their own this.
• Do not use arrow functions for object methods.
• Prefer concise arrow callbacks with implicit return when that stays readable.
• Use method shorthand in object literals.

Collections and objects

• Use array literals ([]) and object literals ({}), not new Array() or new Object().
• Prefer array.push(value) over array[array.length] = value.
• Use object property shorthand when keys and variable names match.
• Use class syntax for classes and extends for inheritance.
• Prefer Object.hasOwn() over Object.prototype.hasOwnProperty().

Control flow and operators

• Always use braces with if, for, while, and similar statements.
• If an if branch ends with return, continue after it instead of adding else.
• Prefer the conditional operator for simple value selection or returns.
• Prefer strict equality operators (===, !==).
• Treat == null as the only acceptable loose-equality exception, and only when intentional.
• Prefer boolean shortcuts like if (value) and if (!value) unless truthy/falsy distinctions matter.

Loops and iteration

• Prefer for...of, .forEach(), or other semantic array methods over index-based for (;;) loops when iterating collections.
• Prefer semantic methods like .map(), .find(), .findIndex(), .includes(), .every(), and similar when they express intent more clearly.
• Never use for...in with arrays or strings.
• Use const in for...of loops and let for counter-based loops.

Strings and coercion

• Use template literals for interpolation.
• Do not use template literals when a plain string literal is sufficient.
• Avoid implicit coercion tricks such as "" + value or +value.
• Use String(value) and Number(value) for explicit conversion.

Async code

• Prefer async/await over long Promise chains when both are practical.
• Keep Promise-based APIs explicit; surface errors instead of swallowing them.
• Use Promise.all() for independent concurrent work and Promise.allSettled() when partial failure is acceptable.
• Use top-level await only when the file is an ECMAScript module and the runtime/toolchain supports it.

Comments

• Use comments to explain intent, constraints, or non-obvious behavior.
• Prefer single-line // comments.
• Put comments on their own lines above the code they describe.
• Do not restate obvious code in prose.
• Use comment-based ellipses for intentionally omitted code in examples.