注释

三条命令（并进 make check）

先看清现状再决定开哪几条，不要一次性把 D 全开——D 里还有一批管标点、管空行、管首字母大写的规则，它们和内容无关。

ruff check --select D103 .
golangci-lint run
cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings

Python：紧贴 def 的三引号字符串

第一行写成完整的一句话，以句号结尾。约束与失败各占一段。

def visible(notes, scope_id):
    """返回属于这个所属范围的笔记。

    约束：scope_id 来自会话，不从请求参数读取。
    失败时：notes 为 None 时抛 TypeError，不做静默兜底。
    """
    return [n for n in notes if n["scope_id"] == scope_id]

Go：紧贴声明、以名字开头

中间不空行。第一行以函数名开头、以句号结尾，这样 go doc 输出才成句。

// Open 打开 path 指向的笔记文件。
//
// 约束：path 来自服务端配置，请求体里的路径不采用。
// 失败时：返回包装过的 error，调用方用 errors.Is 判断。
// 调用方负责关闭返回的文件。
func Open(path string) (*os.File, error) {
	return nil, nil
}

TypeScript：一行够用就写一行

约束多于一句时才展开成多行 JSDoc。eslint:recommended 不检查这段文字在不在。

/** 返回笔记标题，供列表显示。title 为空时返回空串。 */
export function label(note: { title: string }): string {
  return note.title;
}

把本次新增的注释筛出来

只扫新增行。-U0 去掉上下文，避免把没改的老注释卷进来。

git diff main...HEAD -U0 \
  | grep -nE '^\+[[:space:]]*(//|/\*|\*|#|""")'

把没有负责人和日期的 TODO 筛出来

逐条确认每条 TODO 带没带姓名与日期。

git diff main...HEAD -U0 \
  | grep -nE '^\+.*(TODO|FIXME|XXX|HACK)'

助手交出来的样子

// 遍历笔记列表，把可见的追加到结果
for _, n := range notes {
    if n.Visible {
        result = append(result, n)
    }
}

// GetNote 获取笔记
// 参数：id 笔记 ID
// 返回：笔记与错误
func GetNote(id int64) (*Note, error)