代码规范文档

项目代号: A00
项目名称: TJFS集团官方网站及Web服务器
文档类型: 代码规范文档
创建日期: 2026-03-05
编制人: TBs
文档版本: V1.0
文档状态: 已批准

目录

1. 概述
2. 通用规范
3. HTML规范
4. CSS规范
5. JavaScript规范
6. Python规范
7. Git提交规范
8. 代码审查规范

一、概述

1.1 规范目的

1. 提高代码可读性和可维护性
2. 统一团队编码风格
3. 减少代码缺陷
4. 提高开发效率
5. 便于代码审查

1.2 适用范围

本文档适用于TJFS集团官方网站及Web服务器项目（A00）的所有代码开发工作，包括HTML、CSS、JavaScript和Python代码。

1.3 规范原则

1. 一致性: 整个项目保持统一的编码风格
2. 可读性: 代码应该易于阅读和理解
3. 简洁性: 避免过度复杂的实现
4. 可维护性: 便于后续维护和扩展

二、通用规范

2.1 文件编码

• 所有源代码文件统一使用 UTF-8 编码
• 文件末尾保留一个空行
• 不使用BOM头

2.2 缩进与空格

2.3 行长度限制

2.4 命名规范

2.4.1 通用命名规则

2.4.2 命名原则

1. 有意义: 名称应表达其用途和含义
2. 可读性: 易于阅读和发音
3. 可搜索: 便于代码搜索
4. 避免缩写: 除非是通用缩写（如ID, URL）

// 好的命名
var userName = 'John';
var maxConnectionCount = 100;
function calculateTotalPrice(items) { }

// 不好的命名
var n = 'John';
var mcc = 100;
function calc(items) { }

2.5 注释规范

2.5.1 注释原则

1. 代码应该自解释，注释补充说明"为什么"而非"是什么"
2. 保持注释与代码同步更新
3. 避免无意义的注释

2.5.2 文件头注释

<!--
  文件名称: index.html
  功能描述: TJFS集团官网首页
  创建日期: 2026-03-05
  创建人: TBs
  修改记录:
    - 2026-03-10: 添加粒子背景动画
-->

/**
 * 文件名称: main.js
 * 功能描述: 网站主要交互逻辑
 * 创建日期: 2026-03-05
 * 创建人: TBs
 * 修改记录:
 *   - 2026-03-10: 添加导航栏滚动效果
 */

"""
文件名称: start-server.py
功能描述: TJFS Web服务器启动脚本
创建日期: 2026-03-05
创建人: TBs
修改记录:
    - 2026-03-10: 添加CORS支持
"""

2.5.3 函数注释

/**
 * 根据用户ID获取用户信息
 * @param {number} userId - 用户ID
 * @returns {Object|null} 用户对象，不存在返回null
 * @example
 * var user = getUserById(1);
 * console.log(user.name);
 */
function getUserById(userId) {
  // 实现代码
}

三、HTML规范

3.1 基本规范

• 使用HTML5文档类型声明
• 使用语义化标签
• 属性值使用双引号
• 自闭合标签不加斜杠

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>页面标题</title>
</head>
<body>
  <!-- 内容 -->
</body>
</html>

3.2 语义化标签

3.3 属性规范

<!-- 好的写法 -->
<img src="image.jpg" alt="描述文字" width="100" height="100">
<a href="https://example.com" target="_blank" rel="noopener">链接</a>
<input type="text" name="username" required>

<!-- 不好的写法 -->
<img src='image.jpg' alt='描述文字'>
<a href=https://example.com>链接</a>

3.4 可访问性

<!-- 图片添加alt属性 -->
<img src="logo.png" alt="TJFS集团Logo">

<!-- 表单添加label -->
<label for="email">邮箱</label>
<input type="email" id="email" name="email">

<!-- 按钮有明确的文字 -->
<button type="submit">提交</button>

四、CSS规范

4.1 基本规范

• 使用CSS变量管理颜色和尺寸
• 使用Flexbox和Grid进行布局
• 避免使用!important
• 选择器尽量简洁

4.2 文件组织

/* 1. CSS变量 */
:root {
  --primary-color: #1a1a2e;
  --accent-color: #A8FCF3;
}

/* 2. 重置样式 */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

/* 3. 基础样式 */
body {
  font-family: 'Noto Sans SC', sans-serif;
}

/* 4. 布局样式 */
.container {
  max-width: 1200px;
  margin: 0 auto;
}

/* 5. 组件样式 */
.btn {
  padding: 12px 24px;
  border-radius: 8px;
}

/* 6. 工具类 */
.text-center {
  text-align: center;
}

/* 7. 媒体查询 */
@media (max-width: 768px) {
  /* 移动端样式 */
}

4.3 命名规范（BEM）

使用BEM命名规范：Block__Element--Modifier

/* Block */
.card { }

/* Element */
.card__title { }
.card__content { }

/* Modifier */
.card--featured { }
.btn--primary { }

4.4 属性顺序

.selector {
  /* 定位 */
  position: relative;
  top: 0;
  left: 0;
  z-index: 1;
  
  /* 盒模型 */
  display: flex;
  width: 100%;
  height: auto;
  margin: 0;
  padding: 20px;
  
  /* 视觉 */
  background: #fff;
  border: 1px solid #ddd;
  border-radius: 8px;
  
  /* 文字 */
  font-size: 16px;
  color: #333;
  
  /* 其他 */
  transition: all 0.3s ease;
}

五、JavaScript规范

5.1 基本规范

• 使用ES6+语法
• 使用const和let，不使用var
• 使用严格模式
• 使用模板字符串

'use strict';

// 好的写法
const userName = 'John';
let count = 0;

const message = `Hello, ${userName}!`;

// 不好的写法
var name = 'John';
var msg = 'Hello, ' + name + '!';

5.2 函数定义

// 箭头函数
const getUserById = (id) => {
  return users.find(user => user.id === id);
};

// 函数表达式
const initNavbar = function() {
  // 实现
};

// 默认参数
function greet(name = 'Guest') {
  return `Hello, ${name}!`;
}

5.3 对象和数组

// 对象简写
const name = 'John';
const user = { name };  // { name: 'John' }

// 解构赋值
const { id, name, email } = user;
const [first, second] = items;

// 展开运算符
const newUser = { ...user, age: 30 };
const newArray = [...array1, ...array2];

5.4 异步处理

// 使用async/await
const fetchData = async () => {
  try {
    const response = await fetch('/api/data');
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
};

5.5 DOM操作

// 查询元素
const navbar = document.getElementById('navbar');
const buttons = document.querySelectorAll('.btn');

// 事件监听
button.addEventListener('click', (e) => {
  e.preventDefault();
  // 处理逻辑
});

// 创建元素
const div = document.createElement('div');
div.className = 'new-element';
div.textContent = '内容';

5.6 错误处理

try {
  const result = riskyOperation();
  processResult(result);
} catch (error) {
  console.error('Operation failed:', error.message);
  showErrorMessage('操作失败，请稍后重试');
}

六、Python规范

6.1 基本规范

遵循 PEP 8 规范。

6.2 导入规范

# 标准库
import os
import sys
from pathlib import Path

# 第三方库（本项目无）

# 本地模块
from .utils import helper

6.3 函数定义

def create_user(username: str, email: str, is_admin: bool = False) -> dict:
    """
    创建用户
    
    Args:
        username: 用户名
        email: 邮箱地址
        is_admin: 是否为管理员，默认False
        
    Returns:
        用户对象字典
        
    Raises:
        ValueError: 当参数无效时
    """
    if not username:
        raise ValueError('用户名不能为空')
    
    return {
        'username': username,
        'email': email,
        'is_admin': is_admin
    }

6.4 类定义

class CustomHTTPRequestHandler(http.server.SimpleHTTPRequestHandler):
    """自定义HTTP请求处理器"""
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._cache = {}
    
    def end_headers(self):
        """添加CORS头"""
        self.send_header('Access-Control-Allow-Origin', '*')
        super().end_headers()

6.5 异常处理

try:
    with socketserver.TCPServer(("", PORT), handler) as httpd:
        httpd.serve_forever()
except PermissionError:
    print(f'错误: 无法绑定端口 {PORT}')
    sys.exit(1)
except KeyboardInterrupt:
    print('\n服务器已停止')
    sys.exit(0)

七、Git提交规范

7.1 提交信息格式

<type>: <subject>

<body>

<footer>

7.2 提交类型

7.3 提交示例

feat: 添加粒子背景动画

- 实现动态粒子生成
- 添加浮动动画效果
- 优化移动端性能

Closes #5

7.4 分支命名

八、代码审查规范

8.1 审查清单

代码质量

• [ ] 代码是否符合编码规范
• [ ] 命名是否清晰有意义
• [ ] 是否有冗余代码
• [ ] 是否有复杂度过高的代码
• [ ] 是否有重复代码

功能正确性

• [ ] 是否实现了需求要求的功能
• [ ] 边界条件是否处理正确
• [ ] 异常情况是否处理
• [ ] 是否有安全漏洞

可访问性

• [ ] 图片是否有alt属性
• [ ] 表单是否有label
• [ ] 颜色对比度是否足够
• [ ] 是否支持键盘导航

性能

• [ ] 是否有性能瓶颈
• [ ] 动画是否流畅
• [ ] 资源加载是否优化

文档

• [ ] 是否有必要的注释
• [ ] 是否更新了相关文档
• [ ] 函数是否有文档字符串

8.2 审查流程

提交代码 → 自动检查 → 人工审查 → 修改完善 → 合并代码
    │           │           │           │           │
    ▼           ▼           ▼           ▼           ▼
 创建PR     代码检查    审查者审查   作者修改    完成合并

8.3 审查反馈

反馈级别

附录

附录A: 推荐工具

附录B: 推荐阅读

• MDN Web Docs
• Google HTML/CSS Style Guide
• Airbnb JavaScript Style Guide
• PEP 8 -- Style Guide for Python Code

附录C: 变更记录

文档编制日期: 2026-03-05
编制单位: SG Studio - 松果工作室
文档版本: V1.0