阅读 340

【译】“为什么”文档的重要性

“为什么”文档的重要性

帮助未来的工程师们了解决定的来龙去脉

Photo by [Emily Morter](https://unsplash.com/@emilymorter?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/s/photos/why?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)

我们中的许多人曾经盲目地遵循我们所被告知的模式,认为那一定是做这件事情的正确方式。我们就这样照做了,而没有怀疑那个模式对于我们所处的特殊情形是不是最佳选择,或者那个模式从一开始就不够好。

在我们盲目照做的时候,我们放弃了学习和深化理解、专心工作以及最终提高技术的机会。甚至我们为其他同事树立了另一个照做的先例,而不是鼓励他们深入钻研。

女孩和鱼

我最近听说了一则关于一个小女孩儿观察她的妈妈烤鱼的寓言:

一个小女孩儿正看着她的妈妈为晚餐做一条烤鱼。她的妈妈切除了鱼的头和尾巴,然后把剩下的部分放到了烤盘里。

这个小女孩就问她的妈妈:“为什么你要切下鱼的头和尾巴呢?”

她的妈妈想了一会儿,然后说:“我一直是这样做的呀。你的奶奶也是一直这么做的。”

小女孩对这个答案不满意,于是就去拜访了奶奶,想找出她在烤鱼前切掉鱼的头和尾巴的原因。奶奶想了一会儿,然后回答道:“我也不知道。我的妈妈一直是这么做的。”

于是小女孩和她的奶奶就去拜访了曾祖母,询问她是否知道这个答案。曾祖母想了一会儿,然后说:“因为我的烤盘太小了,放不下整条鱼。”

—— 来自 Ptex Group

女孩的妈妈切下了鱼的头和尾巴,因为她没有意识到小烤盘对曾祖母的约束才是需要这样做的原因。当她采用这个菜谱的时候,没有问“为什么”。曾祖母也没有意识到应该告诉她这样做的原因。结果,这个女孩儿的妈妈虽然也能够做鱼,但是她做鱼的方式不是最优的。她是在不了解的情况下做的鱼。

通过问“为什么”,这个小女孩儿可以自信地改变菜谱,因为她知道现在已经没有了当初小烤盘的约束。


在文档中问“为什么”

像这个小女孩一样,我们也想打破在不理解的情况下就做事的循环。为了实现这个目标,我们可以问“为什么”,然后把问题和答案记录在文档里。

代码可以告诉你一个软件系统是如何工作的。文档则告诉你这个系统为什么以这种方式工作。

“代码告诉你做什么,文档告诉你为什么。” —— Steve Konves 在 Hacker Noon 写道。

在我们编程的时候写下“为什么”可以:

  • 减少在不理解的情况下就改动代码所引发的事故的数量。
  • 减少花费在理解软件为什么这样编写上的时间。
  • 在我们的团队中建立一种包含工匠精神和批判性思考的文化。
  • 赋能我们的团队以更好地编程。

什么时候记录“为什么”?

在你编写代码的时候,一直问自己:

是否有某些影响我工作的约束?

我在做的事情中有没有需要解释才能完全明白的?

这些约束可能和这些事情有关:

  • 时间紧迫。
  • 项目资源不足。
  • 我们想要缓解的已知缺陷。
  • 用户流量模式。

一些需要解释的编码方式可能是这样的:

  • 我们为什么决定复制代码而不是复用代码?
  • 我们为什么以这种顺序提交代码?
  • 我们为什么要处理这种特别的极端情况?

把这些限制和解释一一记录下来。

约束的案例

  • 这个功能需要立即发布,所以我们接受较差的代码质量。
  • 我们需要向后兼容我们的 iOS 应用到 1.1 版本,所以我们不得不传递这个额外的参数。
  • 我们预计明天的负载会暴增 100 倍,所以我们增加了基础实例大小。
  • 我们的团队只有三个工程师,所以我们只能支持一种技术栈。
  • 我们的项目的需求不够清晰,所以我们暂时不更新这个功能。

解释的案例

  • 我们复制了博客模型,因为我们想要迁移到一个向后不兼容的模型。
  • 我们在这里避免使用常用的 API,因为在我们这样的用例中,这个 API 会导致性能问题。
  • -$200 的特殊账户余额意味着这是一个员工账户。

如何更容易地发现“为什么”

这篇文章的第二部分会讲述在日常工作中如何使用 Git 来捕捉和你的代码有关的“为什么”。

我们也会复盘 Bytebase 是如何让发现和分享团队工作中隐藏的“为什么”变得容易的。

参考资料

如果发现译文存在错误或其他需要改进的地方,欢迎到 掘金翻译计划 对译文进行修改并 PR,也可获得相应奖励积分。文章开头的 本文永久链接 即为本文在 GitHub 上的 MarkDown 链接。


掘金翻译计划 是一个翻译优质互联网技术文章的社区,文章来源为 掘金 上的英文分享文章。内容覆盖 AndroidiOS前端后端区块链产品设计人工智能等领域,想要查看更多优质译文请持续关注 掘金翻译计划官方微博知乎专栏

文章分类
阅读