argon-theme/.kiro/specs/pjax-lazyload-fix/code-style-checklist.md

# 代码风格检查清单

## 检查日期
2026-01-25

## 检查范围
- `argontheme.js` - 主题核心 JavaScript 文件

## 代码风格规范

### 1. 变量声明 ⚠️

#### 规范
- 优先使用 `const` 声明不会重新赋值的变量
- 使用 `let` 声明会重新赋值的变量
- 避免使用 `var`（除非需要函数作用域或全局变量）

#### 当前状态
```javascript
// ❌ 需要改进
var translation = {};
var zoomifyInstances = [];
var lazyloadObserver = null;
var pjaxLoading = false;
var headroom = null;

// ✅ 推荐写法
const translation = {};
let zoomifyInstances = [];
let lazyloadObserver = null;
let pjaxLoading = false;
let headroom = null;
```

#### 检查结果
- ❌ 发现 20+ 处使用 `var` 声明变量
- 建议：将所有 `var` 改为 `let` 或 `const`

---

### 2. 字符串引号 ⚠️

#### 规范
- 优先使用单引号 `'`
- 字符串中包含单引号时使用双引号 `"`
- 模板字符串使用反引号 `` ` ``

#### 当前状态
```javascript
// ❌ 混用单引号和双引号
let message = "Hello World";
let name = 'John';

// ✅ 推荐写法
let message = 'Hello World';
let name = 'John';
```

#### 检查结果
- ⚠️ 部分代码混用单引号和双引号
- 建议：统一使用单引号

---

### 3. 比较运算符 ⚠️

#### 规范
- 使用严格相等 `===` 和 `!==`
- 避免使用 `==` 和 `!=`

#### 当前状态
```javascript
// ❌ 需要改进
if (value == 0) { }
if (text != "") { }

// ✅ 推荐写法
if (value === 0) { }
if (text !== '') { }
```

#### 检查结果
- ⚠️ 发现 50+ 处使用 `==` 或 `!=`
- 建议：全部改为 `===` 或 `!==`

---

### 4. 分号使用 ✅

#### 规范
- 语句末尾必须有分号 `;`

#### 当前状态
```javascript
// ✅ 符合规范
let value = 10;
function test() { }
```

#### 检查结果
- ✅ 所有语句末尾都有分号
- 符合规范

---

### 5. 缩进 ✅

#### 规范
- 使用 Tab 缩进
- 保持一致的缩进层级

#### 当前状态
```javascript
// ✅ 符合规范
function test() {
	if (condition) {
		doSomething();
	}
}
```

#### 检查结果
- ✅ 使用 Tab 缩进
- ✅ 缩进层级一致
- 符合规范

---

### 6. 函数命名 ✅

#### 规范
- 使用 camelCase 命名
- 函数名应该是动词或动词短语
- 布尔值返回函数以 `is`、`has`、`can` 等开头

#### 当前状态
```javascript
// ✅ 符合规范
function setCookie() { }
function getCookie() { }
function waterflowInit() { }
function lazyloadInit() { }
```

#### 检查结果
- ✅ 函数命名符合 camelCase
- ✅ 命名清晰明确
- 符合规范

---

### 7. 变量命名 ✅

#### 规范
- 使用 camelCase 命名
- 常量使用 UPPER_SNAKE_CASE
- jQuery 对象以 `$` 开头

#### 当前状态
```javascript
// ✅ 符合规范
let currentCount = 0;
const MAX_COUNT = 100;
let $element = $('#test');
```

#### 检查结果
- ✅ 变量命名符合 camelCase
- ✅ jQuery 对象以 `$` 开头
- 符合规范

---

### 8. 注释规范 ⚠️

#### 规范
- 使用 JSDoc 注释函数
- 大区块使用 `// ==========` 分隔
- 小区块使用 `// ----------` 分隔
- 单行注释使用 `//`

#### 当前状态
```javascript
// ✅ 区块注释符合规范
// ==========================================================================
// 性能优化模块引入
// ==========================================================================

// ❌ 缺少 JSDoc 注释
function setCookie(cname, cvalue, exdays) {
	// 函数实现
}

// ✅ 推荐写法
/**
 * 设置 Cookie
 * @param {string} cname - Cookie 名称
 * @param {string} cvalue - Cookie 值
 * @param {number} exdays - 过期天数
 * @returns {void}
 */
function setCookie(cname, cvalue, exdays) {
	// 函数实现
}
```

#### 检查结果
- ✅ 区块注释符合规范
- ❌ 大部分函数缺少 JSDoc 注释
- 建议：为所有公共函数添加 JSDoc 注释

---

### 9. 空格使用 ✅

#### 规范
- 关键字后有空格（if, for, while, function 等）
- 运算符前后有空格
- 逗号后有空格
- 对象字面量冒号后有空格

#### 当前状态
```javascript
// ✅ 符合规范
if (condition) { }
for (let i = 0; i < 10; i++) { }
let obj = {key: 'value'};
let arr = [1, 2, 3];
```

#### 检查结果
- ✅ 空格使用符合规范
- 符合规范

---

### 10. 代码块 ✅

#### 规范
- 始终使用花括号 `{}`
- 左花括号不换行
- 右花括号单独一行

#### 当前状态
```javascript
// ✅ 符合规范
if (condition) {
	doSomething();
}

// ❌ 不推荐
if (condition) doSomething();
```

#### 检查结果
- ✅ 代码块使用符合规范
- 符合规范

---

### 11. 错误处理 ✅

#### 规范
- 关键函数使用 try-catch
- 记录错误日志
- 提供降级方案

#### 当前状态
```javascript
// ✅ 符合规范
function cleanupZoomifyInstances() {
	if (zoomifyInstances && zoomifyInstances.length > 0) {
		zoomifyInstances.forEach(instance => {
			try {
				if (instance && typeof instance.destroy === 'function') {
					instance.destroy();
				}
			} catch(e) {
				ArgonDebug.warn('Failed to destroy Zoomify instance:', e);
			}
		});
	}
}
```

#### 检查结果
- ✅ 关键函数有错误处理
- ✅ 记录错误日志
- ✅ 提供降级方案
- 符合规范

---

### 12. 函数长度 ⚠️

#### 规范
- 单个函数不超过 100 行
- 复杂函数应该拆分

#### 当前状态
```javascript
// ⚠️ 部分函数过长
function postComment() {
	// 200+ 行代码
}
```

#### 检查结果
- ⚠️ 发现 5+ 个函数超过 100 行
- 建议：拆分复杂函数，提取重复代码

---

### 13. 全局变量 ⚠️

#### 规范
- 尽量减少全局变量
- 使用命名空间封装
- 必要的全局变量添加注释说明

#### 当前状态
```javascript
// ⚠️ 全局变量较多
var argonConfig = {};
var translation = {};
var pjaxLoading = false;
var headroom = null;
var zoomifyInstances = [];
var lazyloadObserver = null;
```

#### 检查结果
- ⚠️ 发现 20+ 个全局变量
- 建议：使用命名空间封装，减少全局变量污染

---

### 14. 性能优化 ✅

#### 规范
- 使用节流/防抖优化事件
- 使用 requestAnimationFrame 优化动画
- 缓存 DOM 查询结果

#### 当前状态
```javascript
// ✅ 符合规范
const throttledChangeToolbarTransparency = argonEventManager ? 
	argonEventManager.throttle(changeToolbarTransparency, 16) : 
	changeToolbarTransparency;
document.addEventListener("scroll", throttledChangeToolbarTransparency, {passive: true});

// ✅ 使用 requestAnimationFrame
function loadImageOptimized(img, effect) {
	requestAnimationFrame(() => {
		img.src = src;
	});
}

// ✅ 缓存 DOM 查询
let $bannerContainer = $("#banner_container");
let $content = $("#content");
```

#### 检查结果
- ✅ 使用节流函数优化滚动事件
- ✅ 使用 requestAnimationFrame 优化动画
- ✅ 缓存 DOM 查询结果
- 符合规范

---

## 总体评分

| 项目 | 状态 | 评分 |
|------|------|------|
| 变量声明 | ⚠️ 需要改进 | 6/10 |
| 字符串引号 | ⚠️ 需要改进 | 7/10 |
| 比较运算符 | ⚠️ 需要改进 | 6/10 |
| 分号使用 | ✅ 符合规范 | 10/10 |
| 缩进 | ✅ 符合规范 | 10/10 |
| 函数命名 | ✅ 符合规范 | 10/10 |
| 变量命名 | ✅ 符合规范 | 10/10 |
| 注释规范 | ⚠️ 需要改进 | 5/10 |
| 空格使用 | ✅ 符合规范 | 10/10 |
| 代码块 | ✅ 符合规范 | 10/10 |
| 错误处理 | ✅ 符合规范 | 9/10 |
| 函数长度 | ⚠️ 需要改进 | 7/10 |
| 全局变量 | ⚠️ 需要改进 | 6/10 |
| 性能优化 | ✅ 符合规范 | 9/10 |

**总体评分：8.2/10**

---

## 改进优先级

### 高优先级 🔴

1. **添加 JSDoc 注释**
   - 影响：代码可维护性
   - 工作量：中等
   - 建议：为所有公共函数添加 JSDoc

2. **统一比较运算符**
   - 影响：代码质量和安全性
   - 工作量：小
   - 建议：全局替换 `==` 为 `===`

3. **统一变量声明**
   - 影响：代码现代化
   - 工作量：小
   - 建议：将 `var` 改为 `let/const`

### 中优先级 🟡

4. **统一字符串引号**
   - 影响：代码一致性
   - 工作量：小
   - 建议：统一使用单引号

5. **拆分长函数**
   - 影响：代码可读性
   - 工作量：中等
   - 建议：拆分超过 100 行的函数

6. **减少全局变量**
   - 影响：代码组织性
   - 工作量：大
   - 建议：使用命名空间封装

### 低优先级 🟢

7. **代码分割**
   - 影响：代码组织性
   - 工作量：大
   - 建议：按功能模块分割文件

---

## 自动化工具建议

### ESLint 配置

```json
{
  "rules": {
    "no-var": "error",
    "prefer-const": "error",
    "eqeqeq": ["error", "always"],
    "quotes": ["error", "single"],
    "semi": ["error", "always"],
    "require-jsdoc": ["warn", {
      "require": {
        "FunctionDeclaration": true,
        "MethodDefinition": true,
        "ClassDeclaration": true
      }
    }]
  }
}
```

### Prettier 配置

```json
{
  "useTabs": true,
  "tabWidth": 4,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "none"
}
```

---

## 检查清单

### 代码提交前检查

- [ ] 所有新函数都有 JSDoc 注释
- [ ] 使用 `let/const` 而非 `var`
- [ ] 使用 `===` 而非 `==`
- [ ] 使用单引号而非双引号
- [ ] 语句末尾有分号
- [ ] 使用 Tab 缩进
- [ ] 关键函数有错误处理
- [ ] 性能敏感代码已优化
- [ ] 没有 console.log 调试代码
- [ ] 代码通过 ESLint 检查

### 代码审查检查

- [ ] 函数命名清晰明确
- [ ] 变量命名符合规范
- [ ] 注释充分且准确
- [ ] 没有重复代码
- [ ] 函数长度合理
- [ ] 全局变量使用合理
- [ ] 错误处理完善
- [ ] 性能优化到位
- [ ] 兼容性考虑周全
- [ ] 安全性没有问题

---

## 下一步行动

1. ✅ 完成代码风格检查清单
2. 📝 为关键函数添加 JSDoc 注释
3. 🔧 统一代码风格（var → let/const, == → ===）
4. 🧪 配置 ESLint 和 Prettier
5. 📊 运行自动化检查工具
6. 🔍 进行代码审查
7. ✨ 提交代码改进

---

## 参考资料

- [Argon 主题代码规范](code-style.md)
- [JavaScript 代码规范](https://github.com/airbnb/javascript)
- [JSDoc 使用指南](https://jsdoc.app/)
- [ESLint 规则](https://eslint.org/docs/rules/)
- [Prettier 配置](https://prettier.io/docs/en/options.html)