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

代码风格检查清单

检查日期

2026-01-25

检查范围

• argontheme.js - 主题核心 JavaScript 文件

代码风格规范

1. 变量声明 ⚠️

规范

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

当前状态

// ❌ 需要改进
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. 字符串引号 ⚠️

规范

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

当前状态

// ❌ 混用单引号和双引号
let message = "Hello World";
let name = 'John';

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

检查结果

• ⚠️ 部分代码混用单引号和双引号
• 建议：统一使用单引号

---

3. 比较运算符 ⚠️

规范

• 使用严格相等 === 和 !==
• 避免使用 == 和 !=

当前状态

// ❌ 需要改进
if (value == 0) { }
if (text != "") { }

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

检查结果

• ⚠️ 发现 50+ 处使用 == 或 !=
• 建议：全部改为 === 或 !==

---

4. 分号使用 ✅

规范

• 语句末尾必须有分号 ;

当前状态

// ✅ 符合规范
let value = 10;
function test() { }

检查结果

• ✅ 所有语句末尾都有分号
• 符合规范

---

5. 缩进 ✅

规范

• 使用 Tab 缩进
• 保持一致的缩进层级

当前状态

// ✅ 符合规范
function test() {
	if (condition) {
		doSomething();
	}
}

检查结果

• ✅ 使用 Tab 缩进
• ✅ 缩进层级一致
• 符合规范

---

6. 函数命名 ✅

规范

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

当前状态

// ✅ 符合规范
function setCookie() { }
function getCookie() { }
function waterflowInit() { }
function lazyloadInit() { }

检查结果

• ✅ 函数命名符合 camelCase
• ✅ 命名清晰明确
• 符合规范

---

7. 变量命名 ✅

规范

• 使用 camelCase 命名
• 常量使用 UPPER_SNAKE_CASE
• jQuery 对象以 $ 开头

当前状态

// ✅ 符合规范
let currentCount = 0;
const MAX_COUNT = 100;
let $element = $('#test');

检查结果

• ✅ 变量命名符合 camelCase
• ✅ jQuery 对象以 $ 开头
• 符合规范

---

8. 注释规范 ⚠️

规范

• 使用 JSDoc 注释函数
• 大区块使用 // ========== 分隔
• 小区块使用 // ---------- 分隔
• 单行注释使用 //

当前状态

// ✅ 区块注释符合规范
// ==========================================================================
// 性能优化模块引入
// ==========================================================================

// ❌ 缺少 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 等）
• 运算符前后有空格
• 逗号后有空格
• 对象字面量冒号后有空格

当前状态

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

检查结果

• ✅ 空格使用符合规范
• 符合规范

---

10. 代码块 ✅

规范

• 始终使用花括号 {}
• 左花括号不换行
• 右花括号单独一行

当前状态

// ✅ 符合规范
if (condition) {
	doSomething();
}

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

检查结果

• ✅ 代码块使用符合规范
• 符合规范

---

11. 错误处理 ✅

规范

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

当前状态

// ✅ 符合规范
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 行
• 复杂函数应该拆分

当前状态

// ⚠️ 部分函数过长
function postComment() {
	// 200+ 行代码
}

检查结果

• ⚠️ 发现 5+ 个函数超过 100 行
• 建议：拆分复杂函数，提取重复代码

---

13. 全局变量 ⚠️

规范

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

当前状态

// ⚠️ 全局变量较多
var argonConfig = {};
var translation = {};
var pjaxLoading = false;
var headroom = null;
var zoomifyInstances = [];
var lazyloadObserver = null;

检查结果

• ⚠️ 发现 20+ 个全局变量
• 建议：使用命名空间封装，减少全局变量污染

---

14. 性能优化 ✅

规范

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

当前状态

// ✅ 符合规范
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 配置

{
  "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 配置

{
  "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 主题代码规范
• JavaScript 代码规范
• JSDoc 使用指南
• ESLint 规则
• Prettier 配置