# Argon 主题代码规范

## 项目文件结构

### 核心文件
| 文件 | 说明 | 行数 |
|------|------|------|
| `style.css` | 主题样式，包含所有 CSS | ~12000 行 |
| `argontheme.js` | 主题核心 JS | ~3700 行 |
| `functions.php` | WordPress 函数 | ~5700 行 |
| `settings.php` | 后台设置页面 | ~6000 行 |

### style.css 结构
```
1. CSS 变量定义 (:root)
   - 主题色系统 (--themecolor-*)
   - 颜色变量 (--color-*)
   - 动画系统 (--animation-*, --ease-*)
2. 夜间模式配色 (html.darkmode)
3. AMOLED 夜间模式
4. 沉浸式主题色
5. 主题切换过渡效果
6. Argon 框架样式覆盖
7. 基础样式
8. 页面布局 (单栏/双栏/三栏)
9. 顶栏和 Banner
10. 侧边栏
11. 文章样式
12. 评论区
13. 浮动按钮
14. 响应式适配
```

### argontheme.js 结构
```
1. 兼容性修复 - 第三方库 polyfill
2. 全局配置 - argonConfig 初始化
3. 工具函数 - Cookie、翻译等
4. 顶栏功能 - 透明度、搜索
5. 侧边栏 - 浮动、滚动
6. 文章列表 - 瀑布流布局
7. 浮动按钮 - 回顶、设置
8. 评论系统 - 发送、回复、编辑
9. 代码高亮 - Prism 增强
10. PJAX - 页面无刷新加载
```

### 全局变量（需保留 var）
- `argonConfig` - 主题配置对象
- `translation` - 多语言翻译表
- `pjaxLoading` - PJAX 加载状态
- `headroom` - Headroom 实例

---

## CSS 规范

### 格式化规则
- 使用 Tab 缩进（1 Tab = 4 空格宽度）
- 每个属性独占一行
- 属性之间不要有空行
- 规则块之间保留一个空行
- 选择器与 `{` 之间有一个空格
- 属性值后的 `;` 前不要有空格

### 示例
```css
/* 正确 */
.selector {
	property: value;
	another-property: value;
}

.another-selector {
	property: value;
}

/* 错误 - 属性之间有空行 */
.selector {

	property: value;

	another-property: value;

}
```

### 注释规范
```css
/* ==========================================================================
   大区块标题
   ========================================================================== */

/* ---------- 小区块标题 ---------- */

/* 普通注释 */
```

---

## JavaScript 规范

### 格式化规则
- 使用 Tab 缩进
- 字符串优先使用单引号 `'`
- 比较运算符使用严格相等 `===` 和 `!==`
- 语句末尾必须有分号 `;`
- 函数名与括号之间无空格
- 关键字后有空格（if, for, while, function 等）

### 变量声明
- 优先使用 `let` 和 `const`
- 避免使用 `var`（除非需要函数作用域或全局变量）

### 注释规范
```javascript
// ==========================================================================
// 大区块标题
// ==========================================================================

// ---------- 小区块标题 ----------

/**
 * 函数说明
 * @param {string} param - 参数说明
 * @returns {boolean} 返回值说明
 */
function functionName(param) {
	// 单行注释
	if (param === 'value') {
		return true;
	}
	return false;
}
```

---

## PHP 规范

### 格式化规则
- 使用 Tab 缩进
- 字符串优先使用单引号
- 数组使用短语法 `[]`
- 类名使用 PascalCase
- 函数名使用 snake_case（遵循 WordPress 规范）
- 箭头操作符 `->` 前后不要有空格

### WordPress 特定
- 使用 `esc_html()`, `esc_attr()` 等函数转义输出
- 使用 `wp_nonce_field()` 进行安全验证
- 遵循 WordPress Coding Standards

### 示例
```php
// 正确
$theme->Version
get_option('argon_theme_color')

// 错误
$theme -> Version
```

---

## 规范化历史

### 2026-01-16 规范化
- CSS: 移除 4292 行多余空行，添加结构化注释
- JS: 89 个 var 改为 let，添加模块目录和 JSDoc
- PHP: 修复 200+ 处箭头操作符空格问题
- 备份位置: `tmp/` 目录