文档编写规范

工程化规范的必要性

工程化规范是团队协作的基础，缺乏统一标准会导致代码风格混乱、维护成本增加。以CSS为例，不同开发者可能采用不同命名方式：

/* 开发者A的风格 */
.main_content {}
.sideBar {}

/* 开发者B的风格 */
.main-content {}
.side_bar {}

这种差异在大型项目中会显著降低代码可读性。Google的调研数据显示，遵守统一规范的团队代码审查时间平均减少37%。

文档结构标准化

项目级文档

建议采用分层目录结构：

docs/
├── ARCHITECTURE.md     # 架构设计
├── API.md             # 接口文档
├── CHANGELOG.md       # 变更记录
└── components/        # 组件文档
    └── Button.md

单文件注释规范

JavaScript文件应采用JSDoc标准：

/**
 * 计算商品折扣价格
 * @param {number} originalPrice - 原始价格
 * @param {number} discount - 折扣率(0-1)
 * @returns {number} 折后价格
 * @throws {Error} 当折扣率无效时抛出异常
 */
function calculateDiscount(originalPrice, discount) {
  if (discount < 0 || discount > 1) {
    throw new Error('无效折扣率');
  }
  return originalPrice * (1 - discount);
}

代码风格约束

ESLint配置示例

.eslintrc.js 应包含团队定制规则：

module.exports = {
  rules: {
    'indent': ['error', 2],
    'quotes': ['error', 'single'],
    'react/prop-types': 'off',
    'max-len': ['error', { 
      code: 100,
      ignoreUrls: true 
    }]
  }
};

CSS命名规范

推荐BEM命名法：

/* Block Element Modifier */
.search-form__input--disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

版本控制规范

Git提交消息

采用Angular提交规范：

feat(authentication): add OAuth2 support

- Implement Google OAuth flow
- Add token refresh mechanism
- Update documentation

Closes #123

类型必须是以下之一：

• feat：新功能
• fix：bug修复
• docs：文档变更
• style：代码格式
• refactor：重构
• test：测试相关
• chore：构建过程或辅助工具变更

组件文档示例

Vue组件应包含完整的属性定义：

## Button 按钮

### 基础用法
```vue
<Button type="primary">提交</Button>

Props

Events

## 自动化文档生成

### TypeScript接口文档
使用`typedoc`生成API文档：

```typescript
/**
 * 用户信息接口
 * @remarks
 * 包含用户基本资料和权限信息
 */
interface User {
  /**
   * 用户唯一ID
   * @format uuid
   */
  id: string;
  
  /** 显示名称 */
  displayName: string;
  
  /** 权限等级 1-10 */
  permissionLevel: number;
}

持续集成中的文档检查

在CI流程中加入文档校验：

# .github/workflows/docs.yml
steps:
  - name: Check docs
    run: |
      npx doctoc --check README.md
      npx markdownlint docs/**/*.md

可视化文档系统

Storybook的配置示例：

// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.mdx'],
  addons: [
    '@storybook/addon-docs',
    '@storybook/addon-controls'
  ]
};

组件故事文件应包含交互示例：

// Button.stories.jsx
export const Primary = () => (
  <Button 
    backgroundColor="#ff0"
    label="Button"
    onClick={() => console.log('clicked')}
  />
);

文档可访问性要求

图片必须包含alt文本

<!-- 正确示例 -->
![组件结构图](./structure.png "组件层级关系")

<!-- 错误示例 -->
![](./structure.png)

代码块语言标注

```javascript
// 正确：指定语言类型
function test() {}
```

```plaintext
// 错误：未指定语言
function test() {}
```

文档版本管理

采用语义化版本控制：

docs-v1.2.3/
├── latest/        # 当前稳定版
├── v1.2.2/       # 历史版本
└── v1.1.0/

文档评审机制

建立文档CR清单：

1. 所有接口变更必须同步更新API文档
2. 新增配置项需在CHANGELOG中说明
3. 破坏性变更需标注BREAKING CHANGE
4. 示例代码必须通过ESLint检测

国际化文档处理

多语言文档结构建议：

docs/
├── zh-CN/
│   ├── getting-started.md
│   └── api-reference.md
└── en-US/
    ├── getting-started.md
    └── api-reference.md

使用crowdin等工具管理翻译流程：

# crowdin.yml
files:
  - source: '/docs/en-US/**/*.md'
    translation: '/docs/%locale%/%original_file_name%'

文档性能优化

图片压缩规范

# 使用sharp处理图片
npx sharp input.png -resize 800 -quality 80 output.webp

分块加载策略

将大型文档拆分为多个章节：

[快速开始](./getting-started.md)
[高级配置](./advanced.md)
[API参考](./api.md)

文档反馈机制

在每篇文档底部添加反馈入口：

<div class="doc-feedback">
  <p>本文档对您有帮助吗？</p>
  <button data-response="yes">是</button>
  <button data-response="no">否</button>
</div>

配套的反馈收集脚本：

document.querySelectorAll('[data-response]').forEach(btn => {
  btn.addEventListener('click', () => {
    fetch('/api/feedback', {
      method: 'POST',
      body: JSON.stringify({
        page: location.pathname,
        response: btn.dataset.response
      })
    });
  });
});