Back to Details

bencium-code-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Conventions

代码规范

Core Technologies

核心技术

Frontend: ReactJS, Next.js (App Router structure), TypeScript
Styling: TailwindCSS v3.x (never v4), Shadcn UI
Build Tools: Vite (when applicable)
Backend: Postgres compatible convex.dev or Supabase (always ask, never local postgres)
Deployment: Netlify or Vercel or Fly - suggest
Environment: Mac M2, Python3 with virtual environments, no CUDA, no Docker
Alternative Languages: Avoid python if you can, try using RUST

前端: ReactJS, Next.js (App Router 结构), TypeScript
样式: TailwindCSS v3.x (禁止使用v4版本), Shadcn UI
构建工具: Vite (适用场景下使用)
后端: 兼容Postgres的convex.dev 或 Supabase (务必提前询问，不要使用本地postgres)
部署: 推荐 Netlify、Vercel 或 Fly
开发环境: Mac M2, 带虚拟环境的Python3, 不使用CUDA, 不使用Docker
替代语言: 尽量避免使用python，优先使用RUST

Code Style & Structure

代码风格与结构

Use ES modules (import/export) syntax
Destructure imports when possible
Use TypeScript for all new code
Use async/await instead of Promise chains
Prefer const/let over var; use early returns
Use consts instead of functions:
```
const toggle = () =>
```
. Define types.
Use descriptive variable names with auxiliary verbs (e.g.,
```
isLoading
```
,
```
hasError
```
)
Use lowercase with dashes for directory names (e.g.,
```
components/auth-wizard
```
)

使用ES modules (import/export) 语法
尽可能解构导入
所有新代码使用TypeScript编写
使用async/await代替Promise链式调用
优先使用const/let而非var；使用提前返回
优先使用const定义函数:
```
const toggle = () =>
```
。需要定义类型。
使用带辅助动词的描述性变量名 (例如
```
isLoading
```
,
```
hasError
```
)
目录名使用小写加短横线格式 (例如
```
components/auth-wizard
```
)

Framework Conventions

框架规范

Next.js: Use App Router (app directory) structure and page.tsx files
React: Functional and declarative patterns; avoid classes
State Management: Zustand, TanStack React Query
Validation: Zod for schema validation

Next.js: 使用App Router (app目录) 结构和page.tsx文件
React: 函数式声明式编程模式；避免使用类组件
状态管理: Zustand, TanStack React Query
校验: 使用Zod做 schema 校验

Component Library & Styling

组件库与样式

Component Library: Prefer shadcn components from
```
@/components/ui
```
Styling: Tailwind utility classes
Layout: Grid/flex wrappers with
```
gap
```
for spacing
Icons:
```
@phosphor-icons/react
```
Toasts:
```
sonner
```
for notifications
Always add loading states, spinners, placeholder animations

组件库: 优先使用
```
@/components/ui
```
下的shadcn组件
样式: Tailwind工具类
布局: 带
```
gap
```
间距的Grid/flex容器
图标:
```
@phosphor-icons/react
```
通知: 使用
```
sonner
```
实现toast通知
始终添加加载状态、加载动画、占位符动效

Quality Assurance & Testing

质量保障与测试

TDD: Write failing tests first, commit them, then iterate until suite passes
Never mock tests - if there's a test script, execute all until done
Always write SQL in chunks with test steps after each chunk
Typecheck after making code changes
Run tests before committing
Prefer running single tests for performance, not whole suite

TDD: 先编写失败的测试用例并提交，再迭代开发直到测试集全部通过
不要mock测试 - 如果有测试脚本，执行全部测试直到完成
SQL代码分块编写，每写完一块后执行测试步骤
代码变更后执行类型检查
提交代码前运行测试
为了性能优先运行单个测试，而非整个测试集

Error Handling

错误处理

Implement proper error handling and user input validation
Error messages should be understood by non-technical people
Use early returns for error conditions
Test APIs via curl commands first, then implement in code

实现完善的错误处理和用户输入校验
错误信息应当能被非技术人员理解
错误场景使用提前返回
先通过curl命令测试API，再在代码中实现调用

Performance & Architecture

性能与架构

Minimize
```
'use client'
```
,
```
useEffect
```
,
```
setState
```
; favor RSC and Next.js SSR
Implement dynamic imports for code splitting
Optimize images: WebP format, size data, lazy loading
Favor small, simple, well-named modules

尽量减少
```
'use client'
```
、
```
useEffect
```
、
```
setState
```
的使用；优先使用RSC和Next.js SSR
实现动态导入做代码分割
图片优化：WebP格式、尺寸信息、懒加载
优先编写小型、简单、命名规范的模块

Development Workflow

开发工作流

Process: Explore → Plan → Code → Commit

Read relevant files
Think through a plan
Implement
Then commit
Never local backend, always ask (usually Supabase, Neon)
Minimal dependency, no docker

流程: 调研 → 规划 → 编码 → 提交

阅读相关文件
思考完整的开发计划
实现功能
提交代码
不要使用本地后端，务必提前询问（通常是Supabase、Neon）
最小化依赖，不使用docker

Environment & Deployment

环境与部署

Add .env files for API keys; warn me to save keys in Vercel/Netlify env variables
Write code deployable to Netlify or Vercel; prepare to build locally first
Document progress in progress.md; ask for implementation plan

新增.env文件存储API密钥；提醒我将密钥保存到Vercel/Netlify的环境变量中
编写可部署到Netlify或Vercel的代码；优先在本地完成构建验证
在progress.md中记录开发进度；开发前先确认实现方案