lecture8-beyond code
单项沟通¶
软件工程的很大一部分，是为了那些缺乏你当前背景和上下文的人而写作。需要传达“为什么”，而不只是“做了什么叫”。
代码注释是很重要的
- TODO：标记尚未完成/尚未打磨，还缺什么，为什么延期
- 参考资料：算法的外部链接，自己的改造
- 正确性说明：解释为什么不寻常的代码能产生正确结果
- 血泪教训
- 常数的理由：即使是“随便选的”也要记录
- 承重细节：正确性依赖一个看似无关紧要的实现细节
- “为什么不用”：刻意避开某个做法的理由
- README：回答做什么、为什么、如何用
- commit message：改动原因、备选方案、影响、意外的
| Bash | |
|---|---|
git add -patch非常有用，可以把一个文件的不同改动分别暂存。
| 按键 | 含义 |
|---|---|
y |
暂存当前这块 |
n |
不暂存当前这块 |
q |
退出 |
a |
当前文件后面的块全部暂存 |
d |
当前文件后面的块全部不暂存 |
s |
把当前块继续拆小 |
e |
手动编辑这一块 patch |
? |
查看帮助 |
协作¶
作为工程师，相当一部分时间也是在与他人沟通。
贡献¶
一个好的bug报告：
- 环境
- 期望的结果vs实际发生的情况
- 复现步骤
- 尝试过什么出不调查
无比搜索已经有的问题，提供最小可复现示例，不要经常催维护者（维护者也只是志愿者），熟悉贡献指南，不能提交你自己也解释不了的AI代码
评审¶
评审也是初学者能做的事情，是最快的学习方式之一，能让人培养起对可读代码的直觉。
- 评审代码而非人
- 给出可操作的建议
- 提问而非命令
- 解释为什么
- 区分必须改的和建议
- 肯定做得好的地方
- 知道何时收手
教学互动¶
如何提好的问题、如何获得有用的答案。
AI礼仪¶
要说明如何使用的AI，遵守AI开发规范
Exercise¶
-
浏览一个知名项目（例如 Redis 或 curl）的源码。 找出讲义中提到的几种注释类型：有用的 TODO、指向外部文档的引用、解释为何避开某种做法的“why not”注释、或血泪教训。 如果这些注释不存在，会失去什么？
-
选一个你感兴趣的开源项目，查看最近的提交历史（
git log）。 找到一个能解释“为什么要改”的好提交信息，再找一个只描述“改了什么”的弱提交信息。 对于后者，查看 diff（git show <hash>），尝试按照“问题 → 解决方案 → 影响”结构写一个更好的提交信息。 体会一下：事后补全背景信息是多么费劲！ -
对比三个 1000+ star 的 GitHub 项目的 README。 它们都同样有用吗？ 找出哪些内容在你看来主要是噪音，为你将来写 README 提供借鉴。
-
在一个你使用的项目中找一个未解决 issue（如果有的话，可以看“good first issue”或“help wanted”标签）。 根据讲义中的标准评估它：它是否尊重维护者的时间、包含所有必要信息，还是你预期维护者需要和提交者来回追问多轮才能找到根源？
-
想想你在使用的软件里遇到的一个 bug（或者在 issue tracker 中找一个）。 练习创建一个最小可复现示例：剥离所有与 bug 无关的东西，只留下仍能展示问题的最小案例。 写下你去掉了什么以及为什么。
-
找一个你熟悉项目里已经合并的 PR，其中包含实质性的评审意见（不只是“LGTM”）。 通读整个评审。 所有评论同样高效吗？ 如果你是 PR 作者，收到这些评论的体验会如何？
-
打开 Stack Overflow，找一个你熟悉技术领域内获得高票回答的问题。 再找一个被关闭或大量被点踩的问题。 按照讲义的建议对比它们：能否预见哪个问题更可能得到好答案？