javascript

name	javascript
description	This skill should be used when the user asks to "write JavaScript code", "follow JavaScript style guide", "format JS files", "create Node.js scripts", or needs guidance on JavaScript/Node.js coding standards and best practices.

JavaScript/Node.js Style Guide

Apply Google JavaScript Style Guide conventions to JavaScript and Node.js code. This skill provides essential coding standards, formatting rules, and best practices for writing clean, maintainable JavaScript.

Note: Google recommends migrating to TypeScript. This guide is for JavaScript projects that have not yet migrated.

Core Principles

File Basics

File naming:

• Use lowercase only
• Use underscores (_) or dashes (-) but no other punctuation
• Extension must be .js
• Examples: my_module.js, user-service.js

File encoding:

• UTF-8 only
• Use special escape sequences for special characters (\', \", \\, \b, \f, \n, \r, \t, \v)
• For non-ASCII: use actual Unicode character (e.g., ∞) or hex escape (e.g., \u221e) based on readability

Indentation:

• Use 2 spaces (never tabs)
• No trailing whitespace

Module System

ES Modules (Preferred)

Use import and export statements:

// Imports
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import {name, value} from './sibling.js';

// Named exports only (no default exports)
export class Foo { ... }
export function bar() { ... }

// Or export together
class Foo { ... }
function bar() { ... }
export {Foo, bar};

Import rules:

• Include .js extension in paths (required)
• Use lowerCamelCase for module import names: import * as fileOne from '../file-one.js';
• Keep same name for named imports, avoid aliasing unless necessary
• Do not use default exports
• Import statements are exception to 80-column limit (do not wrap)

Avoid circular dependencies - Do not create import cycles between modules.

Variable Declarations

Use const and let

// Use const by default
const MAX_COUNT = 100;
const users = [];

// Use let only when reassignment needed
let currentIndex = 0;

// NEVER use var

One variable per declaration:

// Good
const a = 1;
const b = 2;

// Bad
const a = 1, b = 2;

Declare close to first use:

// Good - declared when needed
function process(items) {
  // ... some code ...
  const result = items.map(x => x * 2);
  return result;
}

Formatting

Braces

K&R style (Egyptian brackets):

class InnerClass {
  constructor() {}

  method(foo) {
    if (condition(foo)) {
      try {
        something();
      } catch (err) {
        recover();
      }
    }
  }
}

Rules:

• No line break before opening brace
• Line break after opening brace
• Line break before closing brace
• Line break after closing brace (except before else, catch, while, comma, semicolon)

Always use braces for control structures (even single statements):

// Good
if (condition) {
  doSomething();
}

// Exception: single-line if without else
if (shortCondition()) foo();

// Bad
if (condition)
  doSomething();

Column Limit

80 characters with exceptions:

• import and export from statements
• Long URLs, shell commands, file paths in comments
• Lines where wrapping is impossible

Line Wrapping

Break at higher syntactic levels:

// Good
currentEstimate =
    calc(currentEstimate + x * currentEstimate) /
        2.0;

// Bad
currentEstimate = calc(currentEstimate + x *
    currentEstimate) / 2.0;

Continuation lines: indent at least +4 spaces from original line.

Whitespace

Horizontal spacing:

• Space after reserved words: if (, for (, catch (
• No space for function and super: function(, super(
• Space before opening brace: if (x) {, class Foo {
• Space around binary/ternary operators: a + b, x ? y : z
• Space after comma/semicolon: foo(a, b);
• Space after colon in objects: {a: 1, b: 2}
• Space around //: // comment

Vertical spacing:

• Blank line between methods
• Blank lines within methods to create logical groups (sparingly)

Semicolons

Required - Every statement must end with semicolon:

const x = 1;  // Required
doSomething();  // Required

Arrays and Objects

Array Literals

// Use trailing commas
const values = [
  'first value',
  'second value',
];

// Never use Array constructor
const a = [x1, x2, x3];  // Good
const b = new Array(x1, x2, x3);  // Bad

// Destructuring
const [a, b, c, ...rest] = generateResults();
let [, b,, d] = someArray;  // Skip unused elements

// Spread operator
[...foo]  // Preferred over Array.prototype.slice.call(foo)
[...foo, ...bar]  // Preferred over foo.concat(bar)

Object Literals

// Use trailing commas
const obj = {
  a: 0,
  b: 1,
};

// Never use Object constructor
const o = {a: 0, b: 1};  // Good
const o = new Object();  // Bad

// Don't mix quoted and unquoted keys
{
  width: 42,
  height: 50,
}  // Good - all unquoted (struct style)

{
  'width': 42,
  'maxWidth': 43,
}  // Good - all quoted (dict style)

{
  width: 42,
  'maxWidth': 43,
}  // Bad - mixed

// Method shorthand
const obj = {
  value: 1,
  method() {
    return this.value;
  },
};

// Shorthand properties
const foo = 1;
const bar = 2;
const obj = {foo, bar};

// Destructuring
function process({num, str = 'default'} = {}) {}

Classes

Class Declaration

class MyClass {
  // Constructor
  constructor(value) {
    /** @private @const */
    this.value_ = value;
    
    /** @private */
    this.mutableField = 0;
  }

  // Methods
  getValue() {
    return this.value_;
  }

  /** @override */
  toString() {
    return `MyClass(${this.value_})`;
  }
}

// Inheritance
class ChildClass extends MyClass {
  constructor(value, extra) {
    super(value);  // Must call super() first
    this.extra = extra;
  }
}

Rules:

• Constructors are optional
• Define all fields in constructor
• Use @const for never-reassigned fields
• Use @private, @protected for non-public fields
• Private field names may end with underscore
• No semicolons after methods
• Call super() before accessing this in subclasses

Functions

Arrow Functions

Preferred for callbacks and short functions:

// Good
const squares = numbers.map(n => n * n);

items.forEach((item) => {
  process(item);
});

// Use when 'this' from outer scope needed
class Timer {
  start() {
    setInterval(() => {
      this.tick();  // 'this' refers to Timer instance
    }, 1000);
  }
}

Rules:

• Prefer arrow functions for callbacks
• Use arrow functions to preserve this binding
• Omit parens for single parameter: x => x * 2
• Use parens for zero or multiple params: () => 42, (a, b) => a + b
• Always use braces for multi-line bodies

Function Declarations

function myFunction(param1, param2) {
  return param1 + param2;
}

// Optional parameters with defaults
function greet(name = 'Guest') {
  return `Hello, ${name}`;
}

// Rest parameters
function sum(...numbers) {
  return numbers.reduce((a, b) => a + b, 0);
}

Control Structures

Conditionals

// Standard if-else
if (condition) {
  doSomething();
} else if (otherCondition) {
  doOther();
} else {
  doDefault();
}

// Ternary for simple cases
const value = condition ? trueValue : falseValue;

Loops

// For-of for iterables
for (const item of items) {
  process(item);
}

// Traditional for loop
for (let i = 0; i < array.length; i++) {
  process(array[i]);
}

// For-in for object properties (use with caution)
for (const key in object) {
  if (object.hasOwnProperty(key)) {
    process(object[key]);
  }
}

Switch Statements

switch (value) {
  case 'option1':
    handleOption1();
    break;

  case 'option2':
    handleOption2();
    break;

  default:
    handleDefault();
}

Modern Features

Template Literals

// Use for string interpolation
const message = `Hello, ${name}!`;

// Multi-line strings
const html = `
  <div>
    <h1>${title}</h1>
  </div>
`;

Promises and Async/Await

// Prefer async/await
async function fetchData() {
  try {
    const response = await fetch(url);
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Failed:', error);
    throw error;
  }
}

// Promise chains when appropriate
fetch(url)
  .then(response => response.json())
  .then(data => process(data))
  .catch(error => console.error(error));

Comments

Implementation Comments

// Single-line comments use //
// Multiple single-line comments for
// longer explanations.

/*
 * Multi-line comment style.
 * Subsequent lines start with * aligned
 * with the * on the previous line.
 */

// Parameter name comments for clarity
someFunction(obviousParam, /* shouldRender= */ true, /* name= */ 'hello');

JSDoc

Use JSDoc for:

• All classes
• All methods and functions (public and private)
• Properties when needed for clarity

/**
 * Brief description of the function.
 * 
 * @param {string} name The user's name
 * @param {number=} age Optional age parameter
 * @return {string} Greeting message
 */
function greet(name, age) {
  return `Hello, ${name}`;
}

/**
 * Class representing a point.
 */
class Point {
  /**
   * Create a point.
   * @param {number} x The x coordinate
   * @param {number} y The y coordinate
   */
  constructor(x, y) {
    /** @private @const {number} */
    this.x_ = x;
    /** @private @const {number} */
    this.y_ = y;
  }
}

Node.js Specific

Module Exports

// ES modules in Node.js (use .mjs or "type": "module" in package.json)
export class Service {}
export function helper() {}

// CommonJS (when ES modules not available)
class Service {}
function helper() {}

module.exports = {Service, helper};

Error Handling

// Always handle errors in async code
async function processFile(path) {
  try {
    const content = await fs.promises.readFile(path, 'utf8');
    return JSON.parse(content);
  } catch (error) {
    console.error(`Failed to process ${path}:`, error);
    throw error;
  }
}

// Use Error objects
throw new Error('Something went wrong');
throw new TypeError('Expected string');

Common Patterns

Object Property Access

// Check existence
if (obj.property != null) {
  // Property exists and is not null/undefined
}

// Use optional chaining
const value = obj?.deeply?.nested?.property;

// Nullish coalescing
const result = value ?? defaultValue;

Array Operations

// Prefer array methods over loops
const doubled = numbers.map(n => n * 2);
const evens = numbers.filter(n => n % 2 === 0);
const sum = numbers.reduce((acc, n) => acc + n, 0);

// Check if array contains item
if (array.includes(item)) { }

// Find item
const found = array.find(item => item.id === targetId);

Quick Reference

Variable declaration: const (default), let (when reassignment needed), never var
Indentation: 2 spaces
Semicolons: Required
String quotes: Single ' or backticks ` for templates
Braces: K&R style, always use for control structures
Line length: 80 characters
Naming: lowerCamelCase for variables/functions, UpperCamelCase for classes
Imports: Use .js extension, no default exports
Comments: // for single-line, /* */ for multi-line

Additional Resources

Reference Files

For comprehensive coverage of specific topics:

• references/advanced-features.md - Advanced JavaScript patterns, promises, generators, proxies
• references/jsdoc-guide.md - Complete JSDoc annotation guide
• references/naming-conventions.md - Detailed naming rules for all identifier types
• references/disallowed-features.md - Features to avoid and their alternatives

Complete Style Guide

The full Google JavaScript Style Guide is available at: https://google.github.io/styleguide/jsguide.html