代码风格统一方案

团队协作规范的必要性

团队协作开发中，代码风格不一致会导致维护成本增加、代码可读性下降等问题。不同开发者使用不同的缩进方式、命名规则或代码组织模式，会让项目逐渐变得难以维护。统一的代码风格规范能显著提升团队协作效率，降低新人上手成本。

代码格式化工具配置

Prettier是目前最流行的代码格式化工具，支持多种语言。在项目中安装配置：

npm install --save-dev prettier

创建.prettierrc配置文件：

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always"
}

在VS Code中安装Prettier插件并启用"Format On Save"选项，可以自动格式化代码。

ESLint规则定制

ESLint用于检查代码质量问题，结合Prettier使用时需要安装eslint-config-prettier避免规则冲突：

npm install eslint eslint-config-prettier --save-dev

.eslintrc.js配置示例：

module.exports = {
  extends: ['eslint:recommended', 'plugin:react/recommended', 'prettier'],
  rules: {
    'no-console': 'warn',
    'react/prop-types': 'off',
    'no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
  }
};

命名规范统一

变量命名

• 使用camelCase命名变量和函数
• 常量使用UPPER_SNAKE_CASE
• 布尔变量以is/has/should开头

// 好
const MAX_COUNT = 100;
let currentUser = {};
function getUserInfo() {}
const isLoading = true;

// 差
const maxcount = 100;
let CurrentUser = {};
function get_user_info() {}
const loading = true;

组件命名

React组件使用PascalCase，文件名与组件名保持一致：

// UserProfile.jsx
function UserProfile() {
  return <div>...</div>;
}

代码组织结构

文件结构规范

建议按功能组织文件，而不是按类型：

src/
  features/
    user/
      components/
      hooks/
      utils/
      index.js
  shared/
    components/
    styles/
    constants/

组件代码顺序

React组件内部代码建议按以下顺序组织：

import React from 'react';
import PropTypes from 'prop-types';

const MyComponent = ({ prop1, prop2 }) => {
  // 1. 状态hooks
  const [state, setState] = useState();
  
  // 2. 副作用hooks
  useEffect(() => {}, []);
  
  // 3. 处理函数
  const handleClick = () => {};
  
  // 4. 渲染内容
  return <div onClick={handleClick}>{prop1}</div>;
};

MyComponent.propTypes = {
  prop1: PropTypes.string.isRequired,
  prop2: PropTypes.number
};

export default MyComponent;

提交前检查

使用husky和lint-staged在提交前自动检查代码：

npm install husky lint-staged --save-dev

package.json配置：

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}

注释规范

组件注释

复杂组件应添加文件头注释说明用途：

/**
 * 用户信息卡片组件
 * @param {Object} user - 用户数据对象
 * @param {boolean} editable - 是否可编辑
 * @param {Function} onSave - 保存回调
 */
function UserCard({ user, editable, onSave }) {
  // ...
}

复杂逻辑注释

对于复杂算法或业务逻辑，添加详细注释：

// 使用Floyd判圈算法检测链表环
function hasCycle(head) {
  let slow = head;
  let fast = head;
  
  while (fast && fast.next) {
    slow = slow.next;
    fast = fast.next.next;
    
    // 快慢指针相遇说明有环
    if (slow === fast) return true;
  }
  
  return false;
}

样式编写规范

CSS-in-JS规范

使用styled-components时建议：

const Button = styled.button`
  padding: 0.5rem 1rem;
  background: ${props => props.primary ? '#1890ff' : '#fff'};
  color: ${props => props.primary ? '#fff' : '#333'};
  
  &:hover {
    opacity: 0.8;
  }
`;

// 使用
<Button primary>主要按钮</Button>

CSS类名命名

使用BEM命名规范：

.user-card {}
.user-card__header {}
.user-card__avatar--large {}

TypeScript规范

类型定义

优先使用interface定义复杂类型：

interface User {
  id: number;
  name: string;
  age?: number;
}

function getUser(id: number): Promise<User> {
  // ...
}

组件Props类型

React组件Props使用interface定义：

interface Props {
  visible: boolean;
  onClose: () => void;
  title?: string;
}

const Modal: React.FC<Props> = ({ visible, onClose, title }) => {
  // ...
};

代码审查要点

团队代码审查应关注以下方面：

1. 是否符合项目代码风格规范
2. 变量命名是否清晰表达意图
3. 复杂逻辑是否有适当注释
4. 是否引入了不必要的依赖
5. 是否有明显的性能问题
6. 错误处理是否完善

文档配套规范

代码规范应配套文档说明，建议维护以下文档：

1. CODING_GUIDELINES.md - 详细编码规范
2. STYLE_GUIDE.md - UI样式规范
3. ARCHITECTURE.md - 项目架构说明
4. PR_TEMPLATE.md - Pull Request模板

持续集成配置

在CI流程中加入代码检查步骤，.github/workflows/ci.yml示例：

name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: npm install
      - run: npm run lint
      - run: npm run type-check