coding-standards

Coding Standards - General Coding Guidelines for TypeScript/JavaScript/React

Overview

Coding Standards provides a set of general coding guidelines and best practices for TypeScript, JavaScript, React, and Node.js development, covering code quality principles, naming conventions, error handling, performance optimizations, and testing standards.

Applicable Scenarios

1. Team Collaboration and Code Review

When a team needs unified coding standards, this guideline can serve as a checklist for code reviews. It includes clear best practices for variable naming, function naming, component structure, etc., helping team members maintain consistent code style.

2. New Project Initialization and Architecture Design

At the start of a new project, you can refer to the project structure, file naming conventions, and API design standards here to ensure the project is maintainable and extensible from the beginning.

3. Code Refactoring and Quality Improvement

When refactoring existing code or improving code quality, refer to the code smell detection, performance best practices, and testing standards provided here to identify and fix issues in the codebase.

Core Features

1. Code Quality Principles Guide

Provides four core principles: readability first, KISS (Keep It Simple), DRY (Don't Repeat Yourself), and YAGNI (You Aren't Gonna Need It). These principles help developers make better architectural decisions and avoid over-engineering.

2. TypeScript/JavaScript Coding Conventions

Covers variable naming, function naming, type safety, error handling, and asynchronous programming patterns. Emphasizes the immutability pattern, recommending use of the spread operator instead of mutating data directly—this is a key practice in React development.

3. React Best Practices

Includes component type definitions, writing custom hooks, state management, and conditional rendering patterns. Provides a complete example of functional component type definitions and implementations of useful hooks like useDebounce.

4. API Design Standards

Standardizes REST API route naming, HTTP method usage, response formats, and input validation. Examples using Zod for schema validation ensure API robustness.

5. Performance and Testing Optimizations

Includes performance practices such as memoization, lazy loading, and database query optimization, as well as the AAA (Arrange-Act-Assert) testing pattern to help developers write high-quality tests.

6. Code Smell Detection

Identifies common anti-patterns like overly long functions, deep nesting, and magic numbers, and provides corresponding refactoring suggestions.

Frequently Asked Questions

What is the immutability pattern and why is it recommended in TypeScript/React?

The immutability pattern means not modifying existing objects or arrays directly, but creating new copies. In TypeScript you can use the spread operator (...) to achieve this:

const updatedUser = { ...user, name: 'New Name' }
const updatedArray = [...items, newItem]

React recommends immutability because: 1) it makes tracking state changes easier; 2) it simplifies component rendering logic; 3) it works with React.memo to improve performance.

How should Props for React components be correctly typed?

It is recommended to use interface to define clear types, including optional properties and union types:

interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

This gives full type checking and IDE autocomplete, preventing runtime errors.

How to avoid deep nesting in code?

Use the Early Returns pattern to convert multiple nested if statements into sequential condition checks:

// ❌ Deep nesting
if (user) {
  if (user.isAdmin) {
    if (hasPermission) { /* do something */ }
  }
}

// ✅ Early returns
if (!user) return
if (!user.isAdmin) return
if (!hasPermission) return
// do something

This significantly improves code readability and maintainability.

When should useMemo and useCallback be used?

useMemo is used to cache expensive computation results, and useCallback is used to cache function references to avoid unnecessary re-renders of child components. But don’t overuse them—introduce them only when there are real performance issues. Common scenarios include sorting large datasets and passing complex-computation callbacks to child components.

Do these guidelines apply to all projects?

These guidelines provide general best practices, but their implementation should be adjusted based on project size, team preferences, and business requirements. For example, small projects might not need strict file layering, while large enterprise applications require more detailed directory structures. It is recommended to use these guidelines as a starting point and create team-specific coding conventions based on your actual situation.