程序员如何描述清楚线上bug

案例

一个管理后台的bug，把操作记录中的操作员姓名，写成了该操作员的id。原因是修改了一个返回操作人姓名的函数，返回了操作人的id。但是还有其他地方也用这个函数，导致其他地方把姓名字段填写成了操作员的id。
该bug污染了一条修改记录，操作员手动删除就好了。回滚代码后恢复。
本质是修改了函数的返回值，却没有查看所有调用的地方。这个函数的名字叫getinfo，但是在代码的其他模块中也有同名函数，返回的都是id，让修改的人以为都是一个函数，引起了混淆。所以函数名也要修改，做到通过名字能够清晰看出函数功能。
本来很简单的一个线上bug，按照上面的描述几句话就说清楚了，但是一个组员说了一个小时，才勉强让组内的其他同学听明白。
他在描述的时候，先说代码，还有更改代码的背景，而且描述的只言片语，让大家不停提问，花了很多时间。
怎样能够描述清楚线上bug，也是有方法论的，大家可以看看。

描述的顺序

1. 对齐背景
对于线上bug，先描述影响，从用户角度把bug描述清晰。可以把自己想为测试，测试给我们报bug的时候，从来都不会说你代码哪里错了，只是把现象给出，再加上复现的步骤。
同时也说清楚影响范围，多久恢复，让大家放心，知道影响面。
2. 交代错误原因
用直白的语言，说明出错的原理。为什么出错？注意是直白的语言，不是交代代码层面那个函数出错。例如上面的例子，应该说是函数返回值修改导致，而不应该直接说getinfo是一个什么函数，为什么要修改这个函数。
3. 说明引入错误的始末
一般线上bug都是由于变更引起的。究竟是什么变更，为什么会有变更需求，也需要交代清楚。
4. 如何预防
发生bug不可怕，可怕的是重复发生。 吃一堑长一智，不让错误发生第二次，要反思预防的方法，防止再次发生。把预防的方案想好，说出来。
按照上面的顺序会比较清晰、快速地描述清楚线上bug。让听众能够快速了解到影响，和处理方式。

描述清楚线上bug是每个程序员都要必备的能力之一，也是日常经常遇到的场景。掌握先交代背景和影响，再说明错误原因和如何预防，是一种行之有效的描述方法。

---

延伸阅读
通用的方法论可以学习《金字塔原理》《问题的分析与解决》中的SCQA、MECE等方法，这些才是根本，要努力学习和刻意练习才能够掌握。

​