# 编码规范

**分析日期：** 2026-05-21

> 说明：本仓库以 iOS/Swift 为主，未检测到统一的 lint/format 工具配置；代码风格在不同模块间存在差异。文档按项目规则使用中文描述，但代码标识符保持英文。

## 语言与工程约束

- **主要语言**：Swift（Podspec 声明 `s.swift_versions = ["5.10"]`，见 `RDEpubReaderView.podspec`）
- **最低系统版本**：Podspec `iOS 15.0`（`RDEpubReaderView.podspec`），示例工程 Podfile/构建设置里常见为 `iOS 15.6`（`Podfile`）
- **依赖管理**：CocoaPods（`Podfile`、`ReadViewDemo/Podfile`、`Podfile.lock`）

## 命名约定

**文件/类型命名（Swift）：**
- 以类型名为文件名的单文件组织较常见：`Sources/RDEpubReaderView/EPUBCore/RDEPUBParser.swift`
- 大量使用前缀区分模块域：
  - `RD...`：阅读器 UI/控制器相关（如 `Sources/RDEpubReaderView/RDEpubReaderView.swift`、`Sources/RDEpubReaderView/RDEpubURLReaderController.swift`）
  - `RDEPUB...`：EPUB Core/UI/渲染相关（如 `Sources/RDEpubReaderView/EPUBCore/RDEPUBModels.swift`）
- Extension 文件使用 `+` 命名：`Sources/RDEpubReaderView/EPUBUI/RDEPUBReaderController+ContentDelegates.swift`

**变量/函数命名：**
- 基本遵循 Swift lowerCamelCase：`parse(epubURL:)`（`Sources/RDEpubReaderView/EPUBCore/RDEPUBParser.swift`）
- 常量多用 `static let`：`kRDEPUBHighlightAttributeName`（`Sources/RDEpubReaderView/EPUBCore/Models/RDEPUBAnnotationModels.swift`）

## 代码风格与排版（从现有代码归纳）

**缩进与换行：**
- 多数文件使用 4 空格缩进（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift`、`Sources/RDEpubReaderView/EPUBCore/RDEPUBModels.swift`）
- 历史代码中更常见”强制换行/多行括号”风格

**空行与分组：**
- UI 相关文件常用空行分隔属性/初始化/布局段落
- `// MARK:` 用于分区组织（示例：`Sources/RDEpubReaderView/RDEpubReaderGestureController.swift`、`Sources/RDEpubReaderView/EPUBTextRendering/RDEpubPlainTextBookBuilder.swift`）

**类型组织：**
- 偏好用 `extension` 拆分职责/协议实现（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift` 的 `UITableViewDataSource/Delegate`）
- API 暴露处使用 `public`、`public final class`、`public enum/struct`（示例：`Sources/RDEpubReaderView/EPUBCore/RDEPUBModels.swift`）
- “对外只读、内部可写”常用 `public internal(set)`（示例：`Sources/RDEpubReaderView/EPUBCore/RDEPUBParser.swift`）

## 导入与依赖使用

**import：**
- UIKit/UI 文件：`import UIKit`（大量文件）
- Core/模型文件：`import Foundation`（如 `Sources/RDEpubReaderView/EPUBCore/RDEPUBModels.swift`）
- 三方依赖按需引入：
  - `SnapKit`：布局
  - `SSAlertSwift`：弹窗/提示

**Pods 目录说明：**
- `ReadViewDemo/Pods/**` 为依赖源码/生成配置，通常不作为本仓库代码风格的“标准样式”参考。

## 错误处理与日志

- Core 解析层倾向用 `throws` + 自定义 `Error`（示例：`Sources/RDEpubReaderView/EPUBCore/RDEPUBParser.swift`、`Sources/RDEpubReaderView/EPUBCore/RDEPUBModels.swift` 的 `RDEPUBParserError`）
- UI/控制器层常见 `guard` 早返回（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift`）
- 未检测到统一日志框架（未发现专用 logging package/config）；出现时以系统 API/局部输出为主（需按具体文件核对）。

## 注释与文档

- **项目规则（强约束）**：代码标识符保持英文，但**代码注释/文档/提交信息使用中文**（见 `CONTEXT.md`）。
- 历史文件常带 Xcode 头部注释块（示例：`Sources/RDEpubReaderView/ReaderView/RDEpubReaderView.swift`）。
- 公共 API 处存在少量三斜线文档注释（示例：`Sources/RDEpubReaderView/RDEpubReaderView.swift` 的中文说明）。

## Lint / Formatter / 静态检查

**未检测到（仓库根与常见位置）：**
- SwiftLint 配置：`.swiftlint.yml` / `swiftlint.yml`
- SwiftFormat 配置：`.swiftformat`
- 通用格式化配置：`.editorconfig`
- 其他：ESLint/Prettier/Biome 等（本仓库非 JS/TS 主体）

**可执行的工程级格式化/检查：**
- 主要依赖 Xcode（或 Swift 编译器）自身检查；如需引入 SwiftLint/SwiftFormat，应先新增对应配置文件并在 CI/构建脚本中接入。

## Evidence（关键证据文件）

- `CONTEXT.md`
- `Podfile`
- `RDEpubReaderView.podspec`
- `ReadViewDemo/ReadViewDemo/ViewController.swift`
- `Sources/RDEpubReaderView/ReaderView/RDEpubReaderView.swift`
- `Sources/RDEpubReaderView/EPUBCore/RDEPUBParser.swift`
- `Sources/RDEpubReaderView/EPUBCore/RDEPUBModels.swift`
- `Sources/RDEpubReaderView/EPUBUI/RDEPUBReaderController.swift`