86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
# 编码规范
|
||
|
||
**分析日期：** 2026-05-21
|
||
|
||
> 说明：本仓库以 iOS/Swift 为主，未检测到统一的 lint/format 工具配置；代码风格在不同模块间存在差异。文档按项目规则使用中文描述，但代码标识符保持英文。
|
||
|
||
## 语言与工程约束
|
||
|
||
- **主要语言**：Swift（Podspec 声明 `s.swift_versions = ["5.10"]`，见 `RDReaderView.podspec`）
|
||
- **最低系统版本**：Podspec `iOS 15.0`（`RDReaderView.podspec`），示例工程 Podfile/构建设置里常见为 `iOS 15.6`（`Podfile`）
|
||
- **依赖管理**：CocoaPods（`Podfile`、`ReadViewDemo/Podfile`、`Podfile.lock`）
|
||
|
||
## 命名约定
|
||
|
||
**文件/类型命名（Swift）：**
|
||
- 以类型名为文件名的单文件组织较常见：`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`
|
||
- 大量使用前缀区分模块域：
|
||
- `RD...`：阅读器 UI/控制器相关（如 `Sources/RDReaderView/RDReaderView.swift`、`Sources/RDReaderView/RDURLReaderController.swift`）
|
||
- `RDEPUB...`：EPUB Core/UI/渲染相关（如 `Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
|
||
- Extension 文件使用 `+` 命名：`Sources/RDReaderView/EPUBUI/RDEPUBReaderController+ContentDelegates.swift`
|
||
|
||
**变量/函数命名：**
|
||
- 基本遵循 Swift lowerCamelCase：`parse(epubURL:)`（`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`）
|
||
- 常量多用 `static let`：`kRDEPUBHighlightAttributeName`（`Sources/RDReaderView/EPUBCore/Models/RDEPUBAnnotationModels.swift`）
|
||
|
||
## 代码风格与排版（从现有代码归纳）
|
||
|
||
**缩进与换行：**
|
||
- 多数文件使用 4 空格缩进（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift`、`Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
|
||
- 历史代码中更常见”强制换行/多行括号”风格
|
||
|
||
**空行与分组：**
|
||
- UI 相关文件常用空行分隔属性/初始化/布局段落
|
||
- `// MARK:` 用于分区组织（示例：`Sources/RDReaderView/RDReaderGestureController.swift`、`Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift`）
|
||
|
||
**类型组织：**
|
||
- 偏好用 `extension` 拆分职责/协议实现（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift` 的 `UITableViewDataSource/Delegate`）
|
||
- API 暴露处使用 `public`、`public final class`、`public enum/struct`（示例：`Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
|
||
- “对外只读、内部可写”常用 `public internal(set)`（示例：`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`）
|
||
|
||
## 导入与依赖使用
|
||
|
||
**import：**
|
||
- UIKit/UI 文件：`import UIKit`（大量文件）
|
||
- Core/模型文件：`import Foundation`（如 `Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
|
||
- 三方依赖按需引入：
|
||
- `SnapKit`：布局
|
||
- `SSAlertSwift`：弹窗/提示
|
||
|
||
**Pods 目录说明：**
|
||
- `ReadViewDemo/Pods/**` 为依赖源码/生成配置，通常不作为本仓库代码风格的“标准样式”参考。
|
||
|
||
## 错误处理与日志
|
||
|
||
- Core 解析层倾向用 `throws` + 自定义 `Error`（示例：`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`、`Sources/RDReaderView/EPUBCore/RDEPUBModels.swift` 的 `RDEPUBParserError`）
|
||
- UI/控制器层常见 `guard` 早返回（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift`）
|
||
- 未检测到统一日志框架（未发现专用 logging package/config）；出现时以系统 API/局部输出为主（需按具体文件核对）。
|
||
|
||
## 注释与文档
|
||
|
||
- **项目规则（强约束）**：代码标识符保持英文，但**代码注释/文档/提交信息使用中文**（见 `CONTEXT.md`）。
|
||
- 历史文件常带 Xcode 头部注释块（示例：`Sources/RDReaderView/ReaderView/RDReaderView.swift`）。
|
||
- 公共 API 处存在少量三斜线文档注释（示例：`Sources/RDReaderView/RDReaderView.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`
|
||
- `RDReaderView.podspec`
|
||
- `ReadViewDemo/ReadViewDemo/ViewController.swift`
|
||
- `Sources/RDReaderView/ReaderView/RDReaderView.swift`
|
||
- `Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`
|
||
- `Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
|