Component Guidelines

This document defines the standards for creating, naming, and organizing React components in this project.

Overview

We follow a strict functional component pattern with a focus on style isolation, type safety, and clean logic separation. Every component should be modular, self-contained, and well-documented.

Naming Conventions

1. File and Folder Naming

Use kebab-case (xx-xx) for component folders and files.
If the name is short, a single word is acceptable (e.g., button.tsx).
Example: search-bar/reveal.tsx, user-list-item.tsx.

2. Function Naming

Use PascalCase (XxXx) for the component function name.
Example: const SearchBar = () => { ... }.

Component Structure

1. Functional Implementation

All components must be written as Functional Components.

2. Styling & Isolation

File: Create an index.scss file in the same directory as the component.
Root Class: The root div (or container) of the component must have a unique class name.
Isolation: Use SCSS nesting with the unique root class as the parent to ensure style isolation.

// reveal.tsx
import './index.scss';

export const UserCard = () => {
    return (
        <div className="user-card-wrapper">
            <h1 className="title">User Info</h1>
        </div>
    );
};

// index.scss
.user-card-wrapper {
    // Nested styles for isolation
.title {
        color: blue;
    }
}

Props and Type Safety

Props Constraint: Every component with props must define a type/interface to constrain them.
Type Location:
- Single Interface: If the component only needs one interface (usually the Props), define it at the top of the component file, directly below the import statements.
- Multiple Interfaces: If there are 2 or more interfaces/types, create a types.ts file in the same directory. Move all types, including the Props interface, into this file.

Logic and Data Management

1. Static Data Extraction

If a component requires a large amount of static data (e.g., "dead" data for rendering, initialization configs, or constants), do not define them inside the component file.

Move the data to a separate .ts file in the same directory.
Import it using: import { CONFIG_DATA } from "./config.ts".

2.Commenting Standards

Every method, property, interface, and complex logic block MUST be documented.

Language Requirement: All comments inside the code (JSDoc and internal) MUST be written in Chinese.
Mandatory Positive Constraint: Every new interface, type, exported or module-level constant, function component, and business logic function MUST have a JSDoc /** */ comment in Chinese. The only exception is for local variables within a function that are immediately obvious and self-explanatory.
Public API/Props/Interfaces: Use JSDoc style /** ... */ mandatory for every interface definition and every single property within that interface.
Methods & Functions: Every function (exported or internal) must have a /** ... */ comment explaining its purpose, parameters, and return value.
Internal Logic: Use double-slash // for step-by-step explanations inside function bodies.

/**
 * 用户数据
 */
interface UserDetail {
    id: number;
    name: string;
}

interface UserCardProps {
    /** 用户数据详情 */
    data: UserDetail;
}

export const UserCard = ({ data }: UserCardProps) => {
    /**
     *点击用户中心
     */
    const handleProfileClick = () => {
        // 检查用户id
        if (data.id) {
            console.log('Navigating...');
        }
    };

    return <div className="user-card" onClick={handleProfileClick}>...</div>;
};

Summary Checklist

Folder/File name is kebab-case.
Function name is PascalCase.
Props are constrained by a type/interface.
Styles are in index.scss using a unique root class and nesting.
Large static data is moved to a separate .ts file.
Proper use of /** */ for definitions and // for logic.
Types are organized: in-file if single, types.ts if multiple.
CRITICAL: Every interface, property, and method must have Chinese comments using JSDoc (/** */) style.

4.2 KiB Raw Blame History