JavaScript Style Guide

Google JavaScript Style standards for Fulcrum scripts and tooling.

Overview

This guide summarizes key rules from the Google JavaScript Style Guide for JavaScript code in the Fulcrum project (build tools, scripts, configuration files).

For React/Next.js dashboard code, see the TypeScript Style Guide.

Source File Basics

Rule	Standard
File naming	All lowercase, with `_` or `-`
Extension	`.js` (mandatory)
Encoding	UTF-8
Indentation	2 spaces (no tabs)

Module Structure

ES Modules

// New files should use ES modules
import { PolicyEngine } from './policy-engine.js';
import * as utils from './utils.js';

export { evaluatePolicy, PolicyResult };

Export Rules

// Use named exports
export { MyClass };
export { helper1, helper2 };

// DO NOT use default exports
export default MyClass;  // BAD

Import Rules

// Include .js extension in import paths
import { Config } from './config.js';  // Good
import { Config } from './config';     // Bad

// Do not line-wrap imports
import { a, b, c, d } from './module.js';

Formatting

Braces

// Required for all control structures (K&R style)
if (condition) {
  doThing();
}

// Even single-line blocks
if (error) {
  return;
}

Spacing and Limits

Rule	Standard
Column limit	80 characters
Block indent	+2 spaces
Continuation	+4 spaces
Blank lines	Single between methods

Semicolons

// Every statement must end with semicolon
const x = 5;
doThing();
return result;

Language Features

Variable Declarations

// Use const by default
const config = loadConfig();

// Use let only when reassignment is needed
let count = 0;
count++;

// NEVER use var
var x = 5;  // FORBIDDEN

Arrays and Objects

// Use trailing commas
const items = [
  'first',
  'second',
  'third',  // Trailing comma
];

const config = {
  name: 'fulcrum',
  version: '1.0',  // Trailing comma
};

// Use shorthand properties
const name = 'fulcrum';
const obj = { name };  // Instead of { name: name }

// NEVER use constructors
const arr = new Array();    // BAD
const obj = new Object();   // BAD

Strings

// Use single quotes for simple strings
const name = 'fulcrum';

// Use template literals for interpolation or multi-line
const message = `Hello, ${name}!`;

const multiLine = `
  This is a
  multi-line string
`;

Control Structures

// Prefer for-of loops
for (const item of items) {
  process(item);
}

// for-in only for dict-style objects
for (const key in config) {
  if (Object.hasOwn(config, key)) {
    console.log(config[key]);
  }
}

Functions

// Prefer arrow functions for callbacks
items.map((item) => item.name);

// Arrow functions preserve this context
class Handler {
  constructor() {
    this.name = 'handler';
  }

  handle() {
    items.forEach((item) => {
      // this.name is accessible
      console.log(this.name, item);
    });
  }
}

Equality Checks

// ALWAYS use identity operators
if (a === b) { }
if (a !== b) { }

// NEVER use loose equality
if (a == b) { }   // BAD
if (a != b) { }   // BAD

this Keyword

// Only use this in:
// 1. Class constructors
// 2. Class methods
// 3. Arrow functions defined within them

class Service {
  constructor() {
    this.config = {};  // OK
  }

  process() {
    return this.config.value;  // OK
  }

  async processAll(items) {
    // Arrow function preserves this
    return items.map((item) => this.process(item));
  }
}

Disallowed Features

Feature	Reason
`with` keyword	Confusing scope behavior
`eval()`	Security risk
`Function(...string)`	Security risk
ASI reliance	Error-prone
Modifying builtins	Breaks expectations

// All forbidden:
with (obj) { }
eval('code');
new Function('a', 'return a');
Array.prototype.myMethod = function() {};

Naming Conventions

Type	Style	Example
Classes	`UpperCamelCase`	`PolicyEngine`
Functions	`lowerCamelCase`	`evaluatePolicy`
Methods	`lowerCamelCase`	`getConfig`
Constants	`CONSTANT_CASE`	`MAX_RETRIES`
Variables	`lowerCamelCase`	`policyResult`

// Examples
class PolicyEvaluator {
  static MAX_POLICIES = 100;

  constructor() {
    this.evaluationCount = 0;
  }

  evaluatePolicy(policyId) {
    // ...
  }
}

JSDoc

Required Documentation

/**
 * Evaluates a policy against the given request.
 * @param {string} policyId - The policy identifier.
 * @param {Object} request - The request to evaluate.
 * @return {PolicyResult} The evaluation result.
 */
function evaluatePolicy(policyId, request) {
  // ...
}

Type Annotations

/**
 * @param {string} userName - The user's name.
 * @param {number} age - The user's age.
 * @param {boolean} isActive - Whether the user is active.
 * @return {User} The created user object.
 */

Common Tags

Tag	Usage
`@param`	Function parameter
`@return`	Return value
`@override`	Overridden method
`@deprecated`	Deprecated API