JavaScript

Version 0.1.0
Google
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive JavaScript style and best practices guide based on Google's official JavaScript Style Guide, designed for AI agents and LLMs. Contains 47 rules across 8 categories, prioritized by impact from critical (module system, language features) to incremental (formatting). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Module System & Imports — CRITICAL
   • 1.1 Avoid Circular Dependencies — CRITICAL (prevents loading failures and undefined imports)
   • 1.2 Avoid Duplicate Import Statements — HIGH (reduces confusion and bundle overhead)
   • 1.3 Avoid Unnecessary Import Aliasing — HIGH (maintains searchability and code comprehension)
   • 1.4 Follow Source File Structure Order — HIGH (improves navigability and prevents declaration errors)
   • 1.5 Include File Extension in Import Paths — CRITICAL (prevents module resolution failures)
   • 1.6 Prefer Named Exports Over Default Exports — CRITICAL (enables better refactoring and prevents import inconsistencies)
2. Language Features — CRITICAL
   • 2.1 Always Use Explicit Semicolons — HIGH (prevents ASI-related parsing errors)
   • 2.2 Never Modify Built-in Prototypes — CRITICAL (prevents global conflicts and breaking changes)
   • 2.3 Never Use eval or Function Constructor — CRITICAL (prevents code injection and CSP violations)
   • 2.4 Never Use Primitive Wrapper Objects — CRITICAL (prevents type confusion and equality bugs)
   • 2.5 Never Use the with Statement — CRITICAL (prevents scope ambiguity and strict mode errors)
   • 2.6 Use const by Default, let When Needed, Never var — CRITICAL (prevents reassignment bugs and enables optimization)
   • 2.7 Use ES6 Classes Over Prototype Manipulation — HIGH (improves readability and enables tooling support)
   • 2.8 Use Only Standard ECMAScript Features — HIGH (prevents runtime errors on 100% of non-supporting platforms)
3. Type Safety & JSDoc — HIGH
   • 3.1 Always Specify Template Parameters — HIGH (improves type inference and prevents any-type degradation)
   • 3.2 Annotate Enums with Static Literal Values — MEDIUM (enables compiler optimization and type checking)
   • 3.3 Require JSDoc for All Exported Functions — HIGH (enables IDE support and compiler type checking)
   • 3.4 Use Explicit Nullability Modifiers — HIGH (prevents null reference errors)
   • 3.5 Use Parentheses for Type Casts — MEDIUM (prevents Closure Compiler type errors)
   • 3.6 Use typedef for Complex Object Types — MEDIUM-HIGH (enables reusable type definitions across files)
4. Naming Conventions — HIGH
   • 4.1 Avoid Dollar Sign Prefix in Identifiers — MEDIUM (prevents confusion with framework conventions)
   • 4.2 Prefer Descriptive Names Over Brevity — HIGH (significantly improves code comprehension)
   • 4.3 Use CONSTANT_CASE for Deeply Immutable Values — HIGH (signals immutability and prevents accidental modification)
   • 4.4 Use lowerCamelCase for Methods and Variables — HIGH (maintains consistency and enables code search)
   • 4.5 Use Lowercase with Dashes or Underscores for Files — MEDIUM (prevents import resolution failures across platforms)
   • 4.6 Use UpperCamelCase for Classes and Constructors — HIGH (prevents new keyword misuse on non-constructors)
5. Control Flow & Error Handling — MEDIUM-HIGH
   • 5.1 Always Include Default Case in Switch Statements — MEDIUM-HIGH (prevents silent failures on unexpected values)
   • 5.2 Always Throw Error Objects, Not Primitives — MEDIUM-HIGH (preserves stack traces for debugging)
   • 5.3 Document Empty Catch Blocks — MEDIUM (prevents silent failure masking)
   • 5.4 Prefer for-of Over for-in for Iteration — MEDIUM (prevents prototype property bugs)
   • 5.5 Use Strict Equality Except for Null Checks — MEDIUM-HIGH (prevents type coercion bugs)
6. Functions & Parameters — MEDIUM
   • 6.1 Always Use Parentheses Around Arrow Function Parameters — LOW-MEDIUM (prevents errors when adding parameters)
   • 6.2 Prefer Arrow Functions for Nested Functions — MEDIUM (simplifies this binding and reduces boilerplate)
   • 6.3 Use Default Parameters Instead of Conditional Assignment — MEDIUM (clearer API and prevents falsy value bugs)
   • 6.4 Use Rest Parameters Instead of arguments Object — MEDIUM (eliminates Array.prototype.slice.call boilerplate)
   • 6.5 Use Spread Operator Instead of Function.apply — MEDIUM (cleaner syntax, works with new operator)
7. Objects & Arrays — MEDIUM
   • 7.1 Never Mix Quoted and Unquoted Object Keys — MEDIUM (prevents compiler optimization issues)
   • 7.2 Use Array Literals Instead of Array Constructor — MEDIUM (avoids single-argument ambiguity)
   • 7.3 Use Destructuring for Multiple Property Access — MEDIUM (reduces repetition and improves clarity)
   • 7.4 Use Object Literals Instead of Object Constructor — MEDIUM (clearer syntax and avoids edge cases)
   • 7.5 Use Spread Over concat and slice — LOW-MEDIUM (reduces array operation boilerplate by 50%)
   • 7.6 Use Trailing Commas in Multi-line Literals — MEDIUM (reduces git diff noise by 50% on additions)
8. Formatting & Style — LOW
   • 8.1 Always Use Braces for Control Structures — LOW (prevents bugs when adding statements)
   • 8.2 Limit Lines to 80 Characters — LOW (prevents horizontal scrolling in 80-column terminals)
   • 8.3 Place One Statement Per Line — LOW (reduces debugging time by 2-3× with clear breakpoints)
   • 8.4 Use Single Quotes for String Literals — LOW (maintains consistency across codebase)
   • 8.5 Use Two-Space Indentation — LOW (maintains consistent code appearance)

References

1. https://google.github.io/styleguide/jsguide.html
2. https://tc39.es/ecma262/
3. https://developer.mozilla.org/en-US/docs/Web/JavaScript

Source Files

This document was compiled from individual reference files. For detailed editing or extension: