代码之外
写代码只占这份工作的一半，另一半是沟通。注释、README、提交信息是单向记录，写给未来的人看；缺陷报告、PR、评审和提问是双向协商，要等对方回应。两种都先从对方的角度删掉多余的信息。
注释写的是为什么
- 代码回答 what，注释回答 why
- 重复代码的注释是维护负担
- 过时注释比没有注释更危险
- TODO 写清未完成什么、为何推迟
TODO: optimize没有信息量- 引用论文、规范、上游实现
- 外部链接用永久地址，别用行号
- 记录与参考实现之间的差异
- 正确性论证：为什么这些步骤成立
- 踩过的坑写成一条注释
- 魔数说明来源：规范、测试或随手
- 承重实现细节要标注依赖
- 写下「为什么不选显而易见的写法」
- 否则后人会把它「修好」
- 注释密度跟着代码晦涩程度走
README 的四个问题
- README 是陌生人的第一触点
- 一句话说清项目做什么
- 说明为什么值得关心
- 先给用法，再给安装
- 顶部放演示图或最小示例
- 漏斗结构：从秒判到细节
- 示例命令要能直接复制
- 列出依赖与支持的版本
- 常见故障单独一节
- 许可证与贡献入口
- 反例：徽章墙挡住正文
- 反例：只有安装没有用法
- 示例随 API 一起更新
- 文档里的代码也应当被执行
提交信息记录决策
- diff 展示 what，提交信息写 why
- body 回答「什么问题迫使这次改动」
- 列出考虑过的替代方案
- 写明取舍与影响
- 点出可能反直觉的地方
- Problem → Solution → Implications
- 改动越复杂，正文越长
- 一个提交只做一件事
git add -p按 hunk 拆分- 重构与新功能分开提交
- 无关修复不要搭车
git bisect依赖可构建的提交git bisect run用脚本自动二分- LLM 只看得到 diff，看不到上下文
- 让模型反问你缺少的信息
- Conventional Commits 的 type 前缀
--fixup配合--autosquash
缺陷报告
- 维护者时间被严重超订
- 先搜已有 issue，再决定开新的
- 环境：系统、版本、相关配置
- 期望行为与实际行为分开写
- 复现步骤具体到页面与角色
- 写清已经试过什么
- 最小复现比长日志有用
- 不要只贴一屏终端输出
me too评论是噪音- 安全漏洞走私下渠道
- 先看
SECURITY.md - 等两周再礼貌跟进
- issue 模板会引导补齐字段
.github/ISSUE_TEMPLATEgh issue create直接开单
贡献与 PR
- 先读
CONTRIBUTING.md - 从文档、拼写、测试起步
- 大改动先开 issue 对齐方向
- 贡献代码沿用项目许可证
- GPL 的 copyleft 会影响雇主
- 优先向上游提 PR
- fork 留给方向不合的改动
- 一个 PR 只包含一个目的
- 大 PR 按提交拆开供逐个阅读
- 描述解释为什么需要改
- 主动标出需要重点看的部分
- 补上测试方法与取舍
- 一个 diff 可以拆成多个 PR
- 维护者接受 PR 等于长期维护
- 贡献最多的人会被邀请做维护者
- AI 生成的代码你仍要能解释
git range-diff展示改动前后
代码评审
- 评审代码，不评审人
- 意见要可执行
- 用提问代替命令
- 建议后面说明理由
- 区分阻塞项与建议项
- 用
nit:、question:标注语气 - 指出写得好的地方
- 该停就停，别揪住小 nit
- 格式问题交给工具
- 新人视角能暴露隐含假设
- 先读描述与测试，再看实现
- 关注边界、错误路径、命名
- 用
gh pr checkout本地跑一遍 - 复审只看增量
- AI 初审不能替代人审
提问与回答
- 先说出自己的理解再提问
- 用「这样理解对吗」校准
- 用一串是/否问题缩小范围
- 不懂术语当场打断
- 不知道就说不知道
- 补上「但我猜」或「我去查」
- 不接受半截答案
- 复述解释确认理解
- 先做基础调查再问
- 贴最小复现与完整报错
- 描述目标，而不是卡住的解法
- 小心 XY 问题
- 好问题让整个社区受益
- 对 LLM 提问同样适用
- 把结论写回 issue 或文档
AI 使用礼仪
- 用了 AI 就披露
- 说明用了哪一部分
- 区分整段生成与润色
- 遵循团队与项目政策
- 注意合规与数据驻留限制
- 不要把内部代码贴进公共模型
- 学习时别把全程外包
- 目标是练习，不是快速拿答案
- 测评与面试默认不允许
- 不确定就先问
- 明确禁止时不要偷偷用
- AI 生成的 PR 仍需你读懂
- 审查成本不能转给维护者
- 回答要自己验证再转述
Co-authored-by记录共同作者
容易混淆的问题
- 注释写 what 与写 why
- 注释过期与没有注释
- README 的用法与安装顺序
- 提交信息描述 what 与 why
- 一个提交与一个 PR
- 向上游贡献与 fork
- issue 与聊天消息
- 阻塞意见与个人偏好
- 说出理解与直接要答案
- XY 问题与真实目标
- 披露 AI 与隐瞒 AI
- AI 初审与人工评审