Back to Details

frontend-code-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Frontend Code Quality Guidelines

前端代码质量指南

This is a strict guideline. Follow these rules exactly.
Essential guidelines for writing clear, maintainable frontend code.
这是一套严格的指南，请严格遵守这些规则。
编写清晰、可维护前端代码的核心准则。

1. Component Simplicity

1. 组件简洁性

Guideline: Keep components focused on a single responsibility.
tsx
// ❌ Avoid: Component doing too much
function UserDashboard() {
  const [user, setUser] = useState(null);
  const [posts, setPosts] = useState([]);
  const [comments, setComments] = useState([]);
  
  useEffect(() => {
    fetch('/api/user').then(r => r.json()).then(setUser);
    fetch('/api/posts').then(r => r.json()).then(setPosts);
    fetch('/api/comments').then(r => r.json()).then(setComments);
  }, []);
  
  return (
    <div>
      {/* Complex rendering logic for user, posts, comments */}
    </div>
  );
}

// ✅ Preferred: Split into focused components
function UserDashboard() {
  return (
    <div>
      <UserProfile />
      <UserPosts />
      <UserComments />
    </div>
  );
}
Guidelines:
  • Keep files reasonably short, typically not more than 200 lines
  • Extract complex logic to custom hooks or utility functions
  • Avoid nested ternaries and complex conditionals in JSX
tsx
// ❌ Avoid: Complex nested conditionals
{isLoading ? <Spinner /> : error ? <Error /> : data ? <Content data={data} /> : <Empty />}

// ✅ Preferred: Early returns or extracted logic
if (isLoading) return <Spinner />;
if (error) return <Error />;
if (!data) return <Empty />;
return <Content data={data} />;
准则：保持组件遵循单一职责原则。
tsx
// ❌ Avoid: Component doing too much
function UserDashboard() {
  const [user, setUser] = useState(null);
  const [posts, setPosts] = useState([]);
  const [comments, setComments] = useState([]);
  
  useEffect(() => {
    fetch('/api/user').then(r => r.json()).then(setUser);
    fetch('/api/posts').then(r => r.json()).then(setPosts);
    fetch('/api/comments').then(r => r.json()).then(setComments);
  }, []);
  
  return (
    <div>
      {/* Complex rendering logic for user, posts, comments */}
    </div>
  );
}

// ✅ Preferred: Split into focused components
function UserDashboard() {
  return (
    <div>
      <UserProfile />
      <UserPosts />
      <UserComments />
    </div>
  );
}
准则：
  • 保持文件长度合理，通常不超过200行
  • 将复杂逻辑抽离到自定义hook或工具函数中
  • 避免在JSX中使用嵌套三元表达式和复杂条件判断
tsx
// ❌ Avoid: Complex nested conditionals
{isLoading ? <Spinner /> : error ? <Error /> : data ? <Content data={data} /> : <Empty />}

// ✅ Preferred: Early returns or extracted logic
if (isLoading) return <Spinner />;
if (error) return <Error />;
if (!data) return <Empty />;
return <Content data={data} />;

2. State Management Clarity

2. 状态管理清晰度

Guideline: Keep state as close to its usage as possible.
tsx
// ❌ Avoid: Unnecessary state lifting
function App() {
  const [modalOpen, setModalOpen] = useState(false);
  return <UserProfile modalOpen={modalOpen} setModalOpen={setModalOpen} />;
}

// ✅ Preferred: State where it's used
function UserProfile() {
  const [modalOpen, setModalOpen] = useState(false);
  return <Modal open={modalOpen} onClose={() => setModalOpen(false)} />;
}
Guidelines:
  • Lift state only when multiple components need to share it
  • Use context sparingly (auth, theme, global config only)
  • Avoid prop drilling beyond 2-3 levels - use composition or context instead
tsx
// ❌ Avoid: Deep prop drilling
<Parent user={user}>
  <Child user={user}>
    <GrandChild user={user}>
      <GreatGrandChild user={user} />
    </GrandChild>
  </Child>
</Parent>

// ✅ Preferred: Context for deeply shared data
const UserContext = createContext<User | null>(null);

function Parent() {
  const user = useUser();
  return (
    <UserContext.Provider value={user}>
      <Child />
    </UserContext.Provider>
  );
}

function GreatGrandChild() {
  const user = useContext(UserContext);
  return <div>{user.name}</div>;
}
准则：让状态尽可能靠近其使用位置。
tsx
// ❌ Avoid: Unnecessary state lifting
function App() {
  const [modalOpen, setModalOpen] = useState(false);
  return <UserProfile modalOpen={modalOpen} setModalOpen={setModalOpen} />;
}

// ✅ Preferred: State where it's used
function UserProfile() {
  const [modalOpen, setModalOpen] = useState(false);
  return <Modal open={modalOpen} onClose={() => setModalOpen(false)} />;
}
准则：
  • 仅当多个组件需要共享状态时才进行状态提升
  • 谨慎使用context（仅用于鉴权、主题、全局配置场景）
  • 避免超过2-3层的prop透传，可使用组件组合或context替代
tsx
// ❌ Avoid: Deep prop drilling
<Parent user={user}>
  <Child user={user}>
    <GrandChild user={user}>
      <GreatGrandChild user={user} />
    </GrandChild>
  </Child>
</Parent>

// ✅ Preferred: Context for deeply shared data
const UserContext = createContext<User | null>(null);

function Parent() {
  const user = useUser();
  return (
    <UserContext.Provider value={user}>
      <Child />
    </UserContext.Provider>
  );
}

function GreatGrandChild() {
  const user = useContext(UserContext);
  return <div>{user.name}</div>;
}

3. Type Safety

3. 类型安全

Guideline: Define explicit types for all component interfaces.
tsx
// ❌ Avoid: Implicit or missing types
function UserCard({ user, onEdit }) {
  return <div onClick={onEdit}>{user.name}</div>;
}

// ✅ Preferred: Explicit types
interface UserCardProps {
  user: {
    id: string;
    name: string;
    email: string;
  };
  onEdit: (userId: string) => void;
}

function UserCard({ user, onEdit }: UserCardProps) {
  return <div onClick={() => onEdit(user.id)}>{user.name}</div>;
}
Guidelines:
  • Avoid 
    any
    - use 
    unknown
    if type is truly unknown
  • Use discriminated unions for variant components
  • Type event handlers explicitly
tsx
// ✅ Discriminated unions for variants
type ButtonProps = 
  | { variant: 'primary'; onClick: () => void }
  | { variant: 'link'; href: string };

function Button(props: ButtonProps) {
  if (props.variant === 'link') {
    return <a href={props.href}>Link</a>;
  }
  return <button onClick={props.onClick}>Button</button>;
}

// ✅ Explicit event handler types
function SearchInput() {
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    console.log(e.target.value);
  };
  
  return <input onChange={handleChange} />;
}
准则：为所有组件接口定义显式类型。
tsx
// ❌ Avoid: Implicit or missing types
function UserCard({ user, onEdit }) {
  return <div onClick={onEdit}>{user.name}</div>;
}

// ✅ Preferred: Explicit types
interface UserCardProps {
  user: {
    id: string;
    name: string;
    email: string;
  };
  onEdit: (userId: string) => void;
}

function UserCard({ user, onEdit }: UserCardProps) {
  return <div onClick={() => onEdit(user.id)}>{user.name}</div>;
}
准则：
  • 避免使用
    any
    ，如果类型确实未知请使用
    unknown
  • 为多形态组件使用可辨识联合类型
  • 为事件处理函数显式定义类型
tsx
// ✅ Discriminated unions for variants
type ButtonProps = 
  | { variant: 'primary'; onClick: () => void }
  | { variant: 'link'; href: string };

function Button(props: ButtonProps) {
  if (props.variant === 'link') {
    return <a href={props.href}>Link</a>;
  }
  return <button onClick={props.onClick}>Button</button>;
}

// ✅ Explicit event handler types
function SearchInput() {
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    console.log(e.target.value);
  };
  
  return <input onChange={handleChange} />;
}

4. Data Fetching Patterns

4. 数据请求模式

Guideline: Separate data fetching from presentation.
tsx
// ❌ Avoid: Fetching in component
function UserList() {
  const [users, setUsers] = useState([]);
  
  useEffect(() => {
    fetch('/api/users').then(r => r.json()).then(setUsers);
  }, []);
  
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

// ✅ Preferred: Custom hook for data fetching
function useUsers() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    fetch('/api/users')
      .then(r => r.json())
      .then(setUsers)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);
  
  return { users, loading, error };
}

function UserList() {
  const { users, loading, error } = useUsers();
  
  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;
  
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
Guidelines:
  • Handle loading, error, and empty states explicitly
  • Avoid fetching in render - use hooks or effects
  • Cache and deduplicate requests when using data fetching libraries
tsx
// ✅ Handle all states
function DataDisplay() {
  const { data, loading, error } = useData();
  
  if (loading) return <LoadingState />;
  if (error) return <ErrorState error={error} />;
  if (!data || data.length === 0) return <EmptyState />;
  
  return <DataList data={data} />;
}
准则：将数据请求与视图层分离。
tsx
// ❌ Avoid: Fetching in component
function UserList() {
  const [users, setUsers] = useState([]);
  
  useEffect(() => {
    fetch('/api/users').then(r => r.json()).then(setUsers);
  }, []);
  
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

// ✅ Preferred: Custom hook for data fetching
function useUsers() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    fetch('/api/users')
      .then(r => r.json())
      .then(setUsers)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);
  
  return { users, loading, error };
}

function UserList() {
  const { users, loading, error } = useUsers();
  
  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;
  
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
准则：
  • 显式处理加载、错误和空状态
  • 避免在渲染逻辑中发起请求，请使用hook或effect
  • 使用数据请求库时做好请求缓存和去重
tsx
// ✅ Handle all states
function DataDisplay() {
  const { data, loading, error } = useData();
  
  if (loading) return <LoadingState />;
  if (error) return <ErrorState error={error} />;
  if (!data || data.length === 0) return <EmptyState />;
  
  return <DataList data={data} />;
}

5. Naming Conventions

5. 命名规范

Guideline: Use consistent, descriptive names that reveal intent.
tsx
// ❌ Avoid: Unclear or inconsistent names
function Card({ data, fn, flag }) {
  return <div onClick={fn}>{flag && data.txt}</div>;
}

// ✅ Preferred: Clear, consistent names
function UserCard({ user, onEdit, isEditable }: UserCardProps) {
  return <div onClick={onEdit}>{isEditable && user.name}</div>;
}
Conventions:
  • Components: PascalCase (
    UserProfile.tsx
    )
  • Hooks: camelCase with 
    use
    prefix (
    useUserData.ts
    )
  • Utilities: camelCase (
    formatDate.ts
    )
  • Constants: UPPER_SNAKE_CASE (
    API_BASE_URL
    )
  • Boolean props/variables: 
    is
    , 
    has
    , 
    should
    prefix
tsx
// ✅ Boolean naming
interface ModalProps {
  isOpen: boolean;
  hasCloseButton: boolean;
  shouldShowOverlay: boolean;
}

// ✅ Event handler naming
interface FormProps {
  onSubmit: (data: FormData) => void;
  onChange: (field: string, value: string) => void;
  onValidate: (data: FormData) => ValidationResult;
}
准则：使用一致、表意的命名体现代码意图。
tsx
// ❌ Avoid: Unclear or inconsistent names
function Card({ data, fn, flag }) {
  return <div onClick={fn}>{flag && data.txt}</div>;
}

// ✅ Preferred: Clear, consistent names
function UserCard({ user, onEdit, isEditable }: UserCardProps) {
  return <div onClick={onEdit}>{isEditable && user.name}</div>;
}
规范：
  • 组件：使用大驼峰命名（
    UserProfile.tsx
    ）
  • Hooks：使用小驼峰命名，带
    use
    前缀（
    useUserData.ts
    ）
  • 工具函数：使用小驼峰命名（
    formatDate.ts
    ）
  • 常量：使用大写下划线命名（
    API_BASE_URL
    ）
  • 布尔类型props/变量：使用
    is
    、
    has
    、
    should
    作为前缀
tsx
// ✅ Boolean naming
interface ModalProps {
  isOpen: boolean;
  hasCloseButton: boolean;
  shouldShowOverlay: boolean;
}

// ✅ Event handler naming
interface FormProps {
  onSubmit: (data: FormData) => void;
  onChange: (field: string, value: string) => void;
  onValidate: (data: FormData) => ValidationResult;
}

6. File Organization

6. 文件组织

Guideline: Organize by type, not by feature.
frontend/
├── components/          # All components
│   ├── ui/             # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── UserProfile.tsx
│   ├── UserSettings.tsx
│   ├── PostList.tsx
│   └── PostCard.tsx
├── hooks/              # Custom hooks
│   ├── useUser.ts
│   ├── usePost.ts
│   └── useAuth.ts
├── lib/                # Utilities and helpers
│   ├── api/
│   ├── auth/
│   └── utils/
├── types/              # Type definitions
│   ├── user.ts
│   └── post.ts
└── queries/            # API queries (GraphQL, etc.)
    ├── user.ts
    └── post.ts
Why organize by type:
  • High reusability makes feature boundaries blurry
  • Easier to find components when they're used across multiple features
  • Natural fit for component libraries and shared utilities
Guidelines:
  • Group highly related files in subdirectories (e.g., 
    components/ui/
    )
  • Keep shared/reusable code accessible in 
    lib/
    or 
    utils/
  • Separate business logic from UI logic
准则：按文件类型而非功能模块组织。
frontend/
├── components/          # 所有组件
│   ├── ui/             # 可复用UI组件
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── UserProfile.tsx
│   ├── UserSettings.tsx
│   ├── PostList.tsx
│   └── PostCard.tsx
├── hooks/              # 自定义hooks
│   ├── useUser.ts
│   ├── usePost.ts
│   └── useAuth.ts
├── lib/                # 工具和辅助函数
│   ├── api/
│   ├── auth/
│   └── utils/
├── types/              # 类型定义
│   ├── user.ts
│   └── post.ts
└── queries/            # API请求（GraphQL等）
    ├── user.ts
    └── post.ts
按类型组织的优势：
  • 高复用性会让功能模块边界变得模糊
  • 当组件在多个功能中复用时更容易查找
  • 天然适配组件库和共享工具的组织方式
准则：
  • 将高度相关的文件放在子目录下（比如
    components/ui/
    ）
  • 将共享/可复用代码放在
    lib/
    或
    utils/
    目录下方便访问
  • 将业务逻辑与UI逻辑分离

Related Patterns

相关模式

  • Component Organization - Directory structure patterns
  • Core Principles - Universal coding principles
For AI Assistants: Follow these guidelines when writing or reviewing frontend code. Prioritize clarity and maintainability over cleverness.
  • 组件组织 - 目录结构模式
  • 核心原则 - 通用编码原则
致AI助手：编写或评审前端代码时遵循这些准则，优先保障清晰性和可维护性，而非追求巧妙的实现。

Progressive Improvement

持续优化

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.
如果开发者修正了本准则本应避免的行为，请提出对本准则的具体修订建议，避免后续再出现同类问题。