# Code Style and Conventions Standards for JavaScript

This document outlines the coding style and conventions standards for JavaScript development, aiming to promote consistency, readability, and maintainability across all projects. These standards leverage modern JavaScript (ES2024 and beyond) features and best practices. This document is intended to guide developers and inform AI coding assistants.

## 1. General Principles

### 1.1. Consistency

* **Do This:** Adhere strictly to the guidelines outlined in this document.

* **Don't Do This:** Introduce personal stylistic preferences that deviate from these standards unless justified by a specific technical need and approved by the team.

**Why:** Consistent code is easier to read, understand, and maintain. It reduces cognitive load and makes collaboration more efficient.

### 1.2. Readability

* **Do This:** Write code that is easily understandable by other developers (and your future self). Use meaningful variable names, consistent indentation, and clear comments. Prioritize clarity over brevity.

* **Don't Do This:** Write overly complex or obfuscated code. Avoid clever tricks that sacrifice readability for minimal performance gains.

**Why:** Readability is paramount. Well-readable code reduces the likelihood of errors and makes debugging and maintenance faster.

### 1.3. Maintainability

* **Do This:** Design code that is modular, testable, and easy to modify or extend. Follow established design principles like DRY (Don't Repeat Yourself) and SOLID.

* **Don't Do This:** Create tightly coupled, monolithic code that is difficult to refactor or reuse.

**Why:** Maintainable code reduces the long-term cost of ownership. It allows for efficient bug fixes, feature additions, and technology upgrades.

### 1.4. Use of Modern JavaScript Features

* **Do This:** Prefer modern ES2024 (and beyond) features such as "async/await", arrow functions, "const" and "let", class syntax, destructuring, spread syntax, and optional chaining.

* **Don't Do This:** Rely on older, less readable syntax like "var", "function" keyword when arrow functions are appropriate, and verbose conditional checks.

**Why:** Modern JavaScript features often provide more concise, readable, and performant solutions. They also improve code safety and reduce the likelihood of errors.

## 2. Formatting

### 2.1. Indentation

* **Do This:** Use 2 spaces for indentation. Avoid tabs.

* **Don't Do This:** Mix spaces and tabs or use inconsistent indentation.

**Why:** Consistent indentation improves readability and visual structure. Two spaces are widely accepted and provide a good balance between nesting visibility and line length.

"""javascript

// Correct indentation

function processData(data) {

if (data) {

console.log("Data:", data);

}

// Incorrect indentation

function processData(data) {

if (data) {

console.log("Data:", data);

}

"""

### 2.2. Line Length

* **Do This:** Limit lines to a maximum of 80-120 characters. Break long lines for readability.

* **Don't Do This:** Allow lines to exceed the maximum length, making code difficult to read on smaller screens or IDEs.

**Why:** Reasonable line length keeps code readable and prevents horizontal scrolling, especially when viewing code side-by-side or in a code review tool.

"""javascript

// Correct line length

const formattedMessage = "This is a long message that wraps to the next line

to improve readability and maintain a reasonable line length.";

// Incorrect line length

const formattedMessage = "This is a very long message that does not wrap and exceeds the recommended line length making it difficult to read.";

"""

### 2.3. Whitespace

* **Do This:** Use whitespace strategically to improve readability:

* Add a space after commas and colons.

* Add a space around operators (e.g., "=", "+", "-", "*", "/").

* Add blank lines to separate logical blocks of code.

* Add a newline at the end of each file.

* **Don't Do This:** Use excessive or inconsistent whitespace, which can make code harder to scan.

**Why:** Consistent spacing improves visual clarity and makes code easier to parse..

"""javascript

// Correct whitespace

const sum = a + b;

const person = { name: "John", age: 30 };

if (isValid) {

console.log("Valid");

}

// Incorrect whitespace

const sum=a+b;

const person={name:"John",age:30};

if(isValid){

console.log("Valid");

}

"""

### 2.4. Braces

* **Do This:** Use braces for all control flow statements (e.g., "if", "else", "for", "while") even if the block contains only one statement. Place the opening brace on the same line as the statement.

* **Don't Do This:** Omit braces for single-line blocks, as this can lead to errors and reduce readability.

**Why:** Explicit braces improve readability and prevent potential errors when adding statements to a block.

"""javascript

// Correct braces

if (isValid) {

console.log("Valid");

} else {

console.log("Invalid");

}

// Incorrect braces

if (isValid)

console.log("Valid"); // Avoid this

else

console.log("Invalid"); // Avoid this

"""

### 2.5. Semicolons

* **Do This:** Always use semicolons to terminate statements. Relying on automatic semicolon insertion (ASI) can lead to unexpected behavior.

* **Don't Do This:** Omit semicolons at the end of statements, especially assignment ones.

**Why:** Explicit semicolons ensure that statements are interpreted correctly and prevent potential errors caused by ASI.

"""javascript

// Correct semicolons

const message = "Hello";

console.log(message);

// Incorrect semicolons (potential issue with ASI)

const message = "Hello"

console.log(message)

"""

## 3. Naming Conventions

### 3.1. General Naming

* **Do This:**

* Use descriptive and meaningful names.

* Avoid single-letter variable names (except in simple loop counters).

* Use camelCase for variables and function names.

* Use PascalCase for class names and constructor functions.

* Use SCREAMING_SNAKE_CASE for constants.

* **Don't Do This:**

* Use ambiguous or abbreviated names.

* Use names that conflict with reserved keywords.

* Use inconsistent naming conventions.

**Why:** Clear and consistent naming improves readability and makes it easier to understand the purpose of variables, functions, and classes.

"""javascript

// Correct naming

const userName = "John Doe";

function calculateTotal(price, quantity) {

return price * quantity;

}

class Product {

constructor(name, price) {

this.name = name;

this.price = price;

}

const MAX_VALUE = 100;

// Incorrect naming

const a = "John Doe"; // Avoid

function calc(p, q) { // Avoid

return p * q;

}

"""

### 3.2. Variable Naming

* **Do This:** Use noun or noun phrase for variables.

* **Don't Do This:** Use verbs in variable names (unless they are boolean variables).

**Why:** Variable names should clearly indicate what the variable *represents*.

"""javascript

// Correct variable naming

const userAge = 30;

const productList = [];

let isValidUser = true; // Boolean

// Incorrect variable naming

let calculate = 10; // Avoid - use a noun

let adding = true; // Avoid - use 'isAdding' if boolean

"""

### 3.3. Function Naming

* **Do This:** Use verb or verb phrase for function names.

* **Don't Do This:** Use nouns in function names.

**Why:** Function names should clearly indicate what the function *does*.

"""javascript

// Correct function naming

function calculateArea(width, height) {

return width * height;

}

function isValidEmail(email) {

//Email validation logic

return true;

}

// Incorrect function naming

function area(width, height) { // Vague, not descriptive

return width * height;

}

"""

### 3.4. Boolean Variables and Functions

* **Do This:** Prefix boolean variable and function names with "is", "has", or "are".

* **Don't Do This:** Use ambiguous names that do not clearly indicate a boolean value.

**Why:** Consistent naming for boolean variables improves readability and reduces ambiguity.

"""javascript

// Correct boolean naming

let isValid = true;

function hasPermission(user) {

return user.permissions.includes("admin");

}

// Incorrect boolean naming

let valid = true; // Avoid

function permission(user) { // Avoid

return user.permissions.includes("admin");

}

"""

## 4. Stylistic Consistency

### 4.1. Quotes

* **Do This:** Use single quotes ("'") for string literals unless the string contains single quotes itself, in which case use template literals or double quotes (""").

* **Don't Do This:** Mix single and double quotes inconsistently.

**Why:** Consistency improves readability. Single quotes are slightly easier to type and are generally preferred. Template literals offer additional functionality like string interpolation.

"""javascript

// Correct quotes

const name = 'John Doe';

const message = "He said, 'Hello!'";

const greeting = "Hello, ${name}!";

const path = 'c:\\path\\to\\file';

// Incorrect quotes

const name = "John Doe"; // Inconsistent

"""

### 4.2. Arrow Functions vs. Function Declarations

* **Do This:** Prefer arrow functions ("=>") for concise, non-method functions. Use function declarations ("function") for named functions and methods within classes.

* **Don't Do This:** Use arrow functions for complex functions with multiple statements or for methods that require "this" to refer to the class instance.

**Why:** Arrow functions provide a more concise syntax and lexically bind "this". Function declarations are more suitable for named functions and methods that require "this" to refer to the object.

"""javascript

// Correct arrow functions and function declarations

const add = (a, b) => a + b; // Concise arrow function

function multiply(a, b) { // Named function

return a * b;

}

class Calculator {

add(a, b) { // Method using function declaration

return a + b;

}

// Incorrect use of arrow function

const calculator = {

value:0,

add: (a) => {this.value += a;} // WRONG: this will not refer to calculator

}

"""

### 4.3. Object and Array Literals

* **Do This:** Use concise object and array literals:

* Use shorthand property names (e.g., "{ name }" instead of "{ name: name }").

* Use spread syntax ("...") to copy or merge objects and arrays.

* **Don't Do This:** Use verbose or outdated syntax for creating objects and arrays.

**Why:** Concise literals improve readability and reduce boilerplate code.

"""javascript

// Correct object and array literals

const name = "John Doe";

const age = 30;

const person = { name, age }; // Shorthand property names

const numbers = [1, 2, 3];

const moreNumbers = [...numbers, 4, 5]; // Spread syntax

// Incorrect object and array literals

const personOld = { name: name, age: age }; // Verbose

const moreNumbersOld = numbers.concat([4,5]); // Inefficient

"""

### 4.4. Ternary Operators

* **Do This:** Use ternary operators ("condition ? value1 : value2") for simple conditional assignments.

* **Don't Do This:** Use ternary operators for complex logic or nested conditions, as this can reduce readability. Prefer "if/else" statements for complex conditions.

**Why:** Ternary operators provide a concise syntax for simple conditions. However, complex ternary expressions can be difficult to understand and maintain.

"""javascript

// Correct ternary operator

const status = isValid ? "Active" : "Inactive";

// Incorrect ternary operator (too complex)

const result = (a > b) ? (a > c ? a : c) : (b > c ? b : c); // Difficult understand. Avoid this!

"""

## 5. Specific Code Examples and Patterns

### 5.1. Asynchronous Programming with "async/await"

* **Do This:** Prefer "async/await" over callbacks and promises for asynchronous operations.

* **Don't Do This:** Use deeply nested callbacks (callback hell) or neglect error handling in asynchronous code.

**Why:** "async/await" makes asynchronous code easier to read and reason about. It also simplifies error handling with "try/catch" blocks.

"""javascript

// Correct async/await

async function fetchData() {

try {

const response = await fetch("https://api.example.com/data");

const data = await response.json();

return data;

} catch (error) {

console.error("Error fetching data:", error);

throw error; // Re-throw the error to be handled upstream

}

// Incorrect callbacks example (callback hell)

function fetchDataOld(callback) {

fetch("https://api.example.com/data")

.then(response => response.json())

.then(data => {

callback(data);

})

.catch(error => { //Note: this will not handle errors thrown _inside_ the callback.

console.error("Error fetching data:", error);

});

}

"""

### 5.2. Error Handling

* Compile-time validation errors that might arise due to coding mistakes, must be handled gracefully and informative error messages should be displayed to the end-user.

* **Do This:** Implement robust error handling using "try/catch" blocks and "finally" blocks. Handle errors at the appropriate level, either by logging them, displaying user-friendly messages, or re-throwing them for higher-level handling.

* **Don't Do This:** Ignore errors or re-throw them without providing context. Don't rely solely on unhandled promise rejections.

**Why:** Proper error handling prevents unexpected crashes and provides valuable information for debugging and maintenance.

"""javascript

// Correct error handling

async function processData(input) {

try {

// Validate input

if (!input) {

throw new Error("Input cannot be null or undefined.");

}

// Some code that can throw error...

const result = await someAsyncOperation(input);

return result;

} catch (error) {

console.error("Error processing data:", error.message);

// Re-throw the error for higher-level handling

throw new Error("Failed to process input data.", { cause: error });

} finally {

// Clean up resources. This will always execute even if the try block throws.

}

// Incorrect error handling

async function processDataBad(input) {

const result = await someAsyncOperation(input) // What if it throws? No try/catch.

return result; //We might not reach here...but no error reporting!

}

"""

### 5.3. Module Imports and Exports

* **Do This:** Use ES module syntax ("import" and "export") for organizing code into reusable modules.

* **Don't Do This:** Use CommonJS ("require" and "module.exports") unless required maintaining compatibility with older environments.

**Why:** ES modules provide a standardized and more efficient way to organize and load code compared to CommonJS.

"""javascript

// Correct ES modules

// file: utils.js

export function add(a, b) {

return a + b;

}

export const PI = 3.14159;

// file: main.js

import { add, PI } from "./utils.js";

console.log(add(2, 3));

console.log(PI);

// Incorrect CommonJS

// utils.js

// module.exports = {

// add: function(a, b) { return a + b; },

// PI: 3.14159

// };

// main.js

// const utils = require('./utils');

// console.log(utils.add(2, 3));

// console.log(utils.PI);

"""

### 5.4. Immutability

* **Do This:** Favor immutability, especially when working with data transformations. Use methods like "map", "filter", "reduce", and the spread syntax to create new objects and arrays instead of modifying existing ones directly.

* **Don't Do This:** Mutate objects and arrays directly, which can lead to unexpected side effects and make debugging more difficult.

**Why:** Immutability makes code easier to reason about and test. It also prevents unintended side effects and enables more efficient change detection.

"""javascript

// Correct immutability

const numbers = [1, 2, 3];

const squaredNumbers = numbers.map(num => num * num); // Create a new array

const newNumbers = [...numbers, 4]; // Create a new array

// Incorrect mutation

const numbersBad = [1, 2, 3];

numbersBad.push(4); // Mutates the original array! Avoid!

"""

### 5.5. Use of "const" and "let"

* **Do This:** Use "const" for variables that should not be reassigned after their initial value. Use "let" for variables that need to be reassigned. Avoid using "var".

* **Don't Do This:** Use "var" in modern JavaScript code. Use "let" when "const" is more appropriate.

**Why:** "const" and "let" provide block scope and improve code clarity. Using "const" signals that a variable's value should not change, which helps prevent accidental reassignments. "var" has function scope, which can lead to unexpected behavior.

"""javascript

// Correct use of const and let

const userName = "John"; // Value should not change

let age = 30; // Value may change

age = 31; // OK

// Incorrect use of var

var message = "Hello"; // Avoid

function example() {

var x = 10;

if (true) {

var x = 20; // Oops! Overwrites the outer x (function scope)

console.log(x); // 20

}

console.log(x); // 20 (unexpected)

}

example();

"""

### 5.6 Classes and Object-Oriented Programming

* **Do This:** Use ES6 class syntax ("class") for creating objects and using object oriented-programming paradigms.

* **Don't Do This:** Use older approaches to creating class-like structures.

**Why:** ES6 Classes provide a clean syntax and structure for creating objects.

"""javascript

// Correct use of Classes

class Animal {

constructor(name, sound) {

this.name = name;

this.sound = sound;

}

makeSound() {

console.log(this.sound);

}

const dog = new Animal('dog','woof');

dog.makeSound();

"""

### 5.7 Documentation and Comments

* **Do This:** Add comments to explain complex logic, non-obvious code, and the purpose of functions and modules. Use JSDoc syntax liberally.

* **Don't Do This:** Write excessive comments that simply reiterate what the code already does.

"""javascript

/**

* Calculates the area of a rectangle.

* @param {number} width The width of the rectangle.

* @param {number} height The height of the rectangle.

* @returns {number} The area of the rectangle.

function calculateArea(width, height) {

// Multiply width and height to get the area

return width * height;

}

"""

### 5.8 Testing

* **Do This:** Write unit tests for every function and class. Aim for high code coverage.

* **Don't Do This:** Skip testing or write superficial tests that don't thoroughly validate the code.

"""javascript

// Example with Jest

test('adds 1 + 2 to equal 3', () => {

expect(1 + 2).toBe(3);

});

"""

### 5.9 Security Practices

* **Do This:** Sanitize user inputs. Use HTTPS. Prevent Cross-Site Scripting and SQL Injection attacks. Regularly update dependencies for security patches.

* **Don't Do This:** Store sensitive information in client-side code. Neglect security best practices.

These coding standards are designed to ensure the JavaScript code is consistent, readable, and maintainable. Adhering to these guidelines will make collaboration easier and reduce the likelihood of errors. All developers should follow these conventions and continually strive to improve the quality of code.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Code Style and Conventions Standards for JavaScript

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

pnpm over npm

Core Architecture Standards for JavaScript

Component Design Standards for JavaScript

State Management Standards for JavaScript

Performance Optimization Standards for JavaScript