# nb.typ / nb-lib.typ 代码审查

> 参考: Typst 官方文档 + typst-community/package-api-guidelines

---

## 1. 结构问题

### 1.1 set 规则重复

`set text`、`set par` 两个文件都设置，造成冲突：
- `nb.typ:37-49` 设置
- `nb-lib.typ:297-327` 再次设置

**建议**：删除 `nb.typ` 中的设置，仅保留 `nb-lib.typ`

---

### 1.2 注释代码未清理

以下废弃代码应删除（用 git 追溯）：
- `nb.typ:51-63` 旧 `show: nb.with()`
- `nb-lib.typ:30-77` 旧版 `floatc`
- `nb-lib.typ:89-98` 旧版 `outline.entry`
- `nb-lib.typ:385-392` 注释的 `strong` 高亮

---

## 2. 最佳实践问题

### 2.1 魔法数字（Magic Numbers）

**问题**：硬编码尺寸散落各处，难以维护

示例：
```
21cm - 8.5cm   // floatc 函数中
6.0cm          // 页面右边距，多处重复
2.5cm          // 页面边距
```

**建议**：定义常量集中管理
```typst
#let page-margin-left = 2.5cm
#let page-margin-right = 6.0cm
#let float-column-width = 5cm
```

---

### 2.2 show rule 重复定义

**问题**：`<quote>` 标签和内置 `quote` 元素使用相同样式，但代码完全重复

- 第 330-345 行 与 第 347-362 行

**建议**：提取为公共样式函数
```typst
#let quote-style(it) = block(
  fill: rgb("#E4F6F6"),
  radius: 0.5em,
  ...
)
show quote: quote-style
show <quote>: quote-style
```

---

### 2.3 heading show rules 重复

**问题**：level 2/3/4 的 heading 样式几乎相同，仅字号不同

- 第 309-318 行

**建议**：可简化为根据 level 计算字号
```typst
show heading: it => {
  let size = if it.level == 1 { 20pt } 
             else if it.level == 2 { 16pt } 
             else { 14pt }
  block(above: 3em, below: 2em, text(size: size, it.body))
}
```

---

## 3. 可读性与可维护性

### 3.1 函数参数过多（`conf` / `nb`）

**问题**：`conf` 函数有 18 个参数，`nb` 函数有 17 个参数，难以记忆和使用

**建议方案**：
1. 分组为字典参数

```typst
// 当前
conf(title: ..., author: ..., date: ..., ...)

// 改进
conf(
  meta: (title: ..., author: ..., date: ...),
  style: (font: ..., disable-indent: ...),
  layout: (toc-depth: ..., disables: (...)),
)
```

2. 或使用类型定义（Typst 0.12+ 支持）

---

### 3.2 缺乏文档注释

**问题**：大部分函数缺少参数说明，仅有零星中文注释

**建议**：为每个 public 函数添加文档注释
```typst
/// 全页图片显示
/// - img: 图片路径（字符串）
/// - fit: 填充方式 "cover"/"contain"/"stretch"
/// - bg: 背景色
#let fullimage(img, fit: "contain", bg: white) = { ... }
```

---

## 4. 潜在问题

### 4.1 `content-to-string` 递归没有类型检查

**问题**：假设 content 一定有 `.has` 方法，边界情况可能报错

```typst
// 第 9 行
let result = if content.has("text") { ... }
```

**建议**：添加类型检查
```typst
if type(content) == content and content.has("text") { ... }
```

---

### 4.2 表格宽度处理可能越界

**问题**：强制 140% 宽度 + 15% 偏移，在窄内容时可能出问题

```typst
// 第 375-383 行
width: 140%,
dx: 15%,
```

**建议**：考虑使用 `measure` 判断实际宽度

---

## 5. 代码风格建议

| 问题 | 位置 | 建议 |
|------|------|------|
| 括号冗余 | `if(not disable_cover)` | 改为 `if not disable_cover` |
| 一致性 | `disable-indent` vs `disable-cover` | 统一命名风格 |
| 魔法颜色 | `#00008B`, `#E4F6F6` | 提取为命名变量 |

---

## 6. 优先级建议

| 优先级 | 修改项 |
|--------|--------|
| 🔴 高 | 删除重复的 set 规则 |
| 🔴 高 | 清理注释代码块 |
| 🟡 中 | 提取魔法数字为常量 |
| 🟡 中 | 合并重复的 show rules |
| 🟢 低 | 函数参数重组 |
| 🟢 低 | 添加文档注释 |
