Javascript Code Style Guideline

Last Updated: April 20, 2025

This document outlines the preferred JavaScript coding style, covering formatting, naming conventions, and best practices to promote code clarity, maintainability, and collaboration within the project/team.

---

Preview

1. Code Formatting:

• Objects and Arrays: Always single-line unless it will exceed our defined line length limit (to be determined, e.g., 100 characters). For longer objects and arrays, use multi-line formatting with consistent indentation, placing each property or element on a new line.

// Single-line array (fits within 100 characters)
const shortArray = [1, 2, 3, 4, 5];

// Multi-line object (exceeds 100 characters)
const longObject = {
  firstName: 'Robert',
  lastName: 'Smith',
  occupation: 'Software Engineer',
  company: 'Example Corp',
  address: '123 Main St, Anytown, USA',
  email: 'robert.smith@example.com',
  phone: '+1-555-123-4567',
};

• Functions: Always use arrow functions (const fn = () => {}) except when this binding or hoisting is specifically needed (e.g., object methods, constructors if not using classes).

• Imports: Group import statements as follows, with alphabetical sorting within each group:

  • Built-in Node.js modules (e.g., fs, path).
  • External packages (from node_modules, e.g., react, lodash).
  • Internal modules (paths within our project, using absolute or relative paths, potentially with path aliases like @/).

• React Components:

  • Order within components should prioritize grouping related functionality together. While flexibility is allowed based on the component’s logic, a general suggestion is:
  • Props (implicitly defined).
  • State (using useState or class this.state).
  • Event handlers (functions to handle user interactions).
  • Side effects/Lifecycle methods (useEffect or class lifecycle methods).
  • Utility functions (helper functions used within the component).
  • render method (for class components) or the return statement (for functional components).

• JSX Formatting: Always single-line unless it will exceed our defined line length limit. For longer elements, break props onto new lines with consistent indentation.

• Self-Closing Tags: Use self-closing or explicit closing tag accordingly. With children: If a React component can potentially contain other elements or text, you must use the explicit opening and closing tags. Without children: If a React component does not have any content, you can use a self-closing tag instead.

  • Curly Braces in JSX: If the expression inside curly braces for dynamic values is long or complex, break it onto a new line with indentation.
  • Conditional Rendering in JSX: Always use ternary operators (condition ? <A /> : <B />).
  • Inline Styles: Avoid inline styles as much as possible. Prefer CSS Modules or styled-components for managing component styling.

2. Variables:

• Always use const for variables that will not be reassigned.
• Use let for variables that need to be reassigned.
• Never use var.

3. Asynchronous Operations:

• Primarily use async/await for handling asynchronous operations.

4. Error Handling:

• Use try...catch blocks within async functions to handle potential errors.

5. Comments:

• Minimize comments as much as possible. Aim for self-documenting code through clear naming and well-structured logic. Comment complex or non-obvious logic sparingly.

6. Naming Conventions:

• Use camel case (camelCase) for variables and function names.
• Use Pascal case (PascalCase) for React component names and class names.
• Use prefixes like is, has, should, will for boolean variable names (e.g., isActive, hasError).
• Use all uppercase with underscores separating words (UPPER_SNAKE_CASE) for constant variables (e.g., MAX_VALUE, API_KEY).

7. Project Structure:

• Organize project directories and files using a feature-based grouping.
• Maintain a dedicated utils folder for common utility functions.
• Maintain a dedicated components folder for reusable UI components.

8. Adherence to Guidelines:

• These coding style guidelines are strict rules that must be followed without exception.
• Any deviations or requests for changes to these guidelines must be proposed and discussed by the team, requiring a consensus or majority vote for adoption.

9. Enforcement:

• These guidelines will be enforced through a combination of automated tools (linters like ESLint and formatters like Prettier, configured according to these rules) and thorough code reviews.

10. Updates to Guidelines:

• Changes to these coding style guidelines should be proposed and discussed by the team. A consensus or majority vote will be required for adoption.

---

Markdown Version

### 1. Code Formatting:

* **Objects and Arrays:** Always single-line unless it will exceed our defined line length limit (to be determined, e.g., 100 characters). For longer objects and arrays, use multi-line formatting with consistent indentation, placing each property or element on a new line.

```code
// Single-line array (fits within 100 characters)
const shortArray = [1, 2, 3, 4, 5];

// Multi-line object (exceeds 100 characters)
const longObject = {
  firstName: 'Robert',
  lastName: 'Smith',
  occupation: 'Software Engineer',
  company: 'Example Corp',
  address: '123 Main St, Anytown, USA',
  email: 'robert.smith@example.com',
  phone: '+1-555-123-4567',
};
```

* **Functions:** Always use arrow functions (`const fn = () => {}`) except when `this` binding or hoisting is specifically needed (e.g., object methods, constructors if not using classes).

* **Imports:** Group import statements as follows, with alphabetical sorting within each group:
  * Built-in Node.js modules (e.g., `fs`, `path`).
  * External packages (from `node_modules`, e.g., `react`, `lodash`).
  * Internal modules (paths within our project, using absolute or relative paths, potentially with path aliases like `@/`).

* **React Components:**
  * Order within components should prioritize grouping related functionality together. While flexibility is allowed based on the component's logic, a general suggestion is:
  * Props (implicitly defined).
  * State (using `useState` or class `this.state`).
  * Event handlers (functions to handle user interactions).
  * Side effects/Lifecycle methods (`useEffect` or class lifecycle methods).
  * Utility functions (helper functions used within the component).
  * `render` method (for class components) or the `return` statement (for functional components).

* **JSX Formatting:** Always single-line unless it will exceed our defined line length limit. For longer elements, break props onto new lines with consistent indentation.

* **Self-Closing Tags:** Use self-closing or explicit closing tag accordingly.
With children: If a React component can potentially contain other elements or text, you must use the explicit opening and closing tags.
Without children: If a React component does not have any content, you can use a self-closing tag instead.

  * **Curly Braces in JSX:** If the expression inside curly braces for dynamic values is long or complex, break it onto a new line with indentation.
  * **Conditional Rendering in JSX:** Always use ternary operators (`condition ? <A /> : <B />`).
  * **Inline Styles:** Avoid inline styles as much as possible. Prefer CSS Modules or styled-components for managing component styling.

### 2. Variables:

* Always use `const` for variables that will not be reassigned.
* Use `let` for variables that need to be reassigned.
* Never use `var`.

### 3. Asynchronous Operations:

* Primarily use `async/await` for handling asynchronous operations.

### 4. Error Handling:

* Use `try...catch` blocks within `async` functions to handle potential errors.

### 5. Comments:

* Minimize comments as much as possible. Aim for self-documenting code through clear naming and well-structured logic. Comment complex or non-obvious logic sparingly.

### 6. Naming Conventions:

* Use camel case (`camelCase`) for variables and function names.
* Use Pascal case (`PascalCase`) for React component names and class names.
* Use prefixes like `is`, `has`, `should`, `will` for boolean variable names (e.g., `isActive`, `hasError`).
* Use all uppercase with underscores separating words (`UPPER_SNAKE_CASE`) for constant variables (e.g., `MAX_VALUE`, `API_KEY`).

### 7. Project Structure:

* Organize project directories and files using a feature-based grouping.
* Maintain a dedicated `utils` folder for common utility functions.
* Maintain a dedicated `components` folder for reusable UI components.

### 8. Adherence to Guidelines:

* These coding style guidelines are strict rules that must be followed without exception.
* Any deviations or requests for changes to these guidelines must be proposed and discussed by the team, requiring a consensus or majority vote for adoption.

### 9. Enforcement:

* These guidelines will be enforced through a combination of automated tools (linters like ESLint and formatters like Prettier, configured according to these rules) and thorough code reviews.

### 10. Updates to Guidelines:

* Changes to these coding style guidelines should be proposed and discussed by the team. A consensus or majority vote will be required for adoption.