[中英对照]The Art Of Reporting Bugs | 报bug的艺术

前言：因为最近要给兄弟Team分享一下如何有效地报告bug, 故多做一做功课。下面给出一篇博客的中英文对照翻译。

The Art Of Reporting Bugs | 报bug的艺术

My initial intention was do a write-up on debugging tips, then it dawned on me that even before debugging an issue,  there needs be an emphasis on how the bug is being reported. So in this post I want to share my takes and thoughts in reporting a bug. A small precursor, I work in a semiconductor company and so my bugs are Hardware/ Software or maybe combination of both. Thus it becomes that much complex for the engineer or the engineering team to fix the bug reported by customers. These tips should be useful for reporting any kind of bug (i.e. Hardware or Software)

本来是打算写点儿有关调试技巧的，然而我意识到，在调试一个问题之前，还需要强调一下bug是如何被报告的。所以，在这篇文章中，我想就如何报bug的话题，分享一下我的观点和想法。先简单介绍一下背景，本人在一家半导体公司工作，所以我遇到的bug，要么是硬件bug, 要么是软件bug, 或者软硬件结合产生的bug。因此，对工程师或者工程师团队来说，客户报告的bug可以说是相当复杂的，修复起来可不是一件容易的事情。下面要介绍的tips因此是相当有用的，对于报告任何类型的bug(即硬件bug或者软件bug)来说。

Being in Applications team more often than not we are the ones that escalate the customer bugs to Engineering. What I learned is that the effort put into reporting a bug is much  important as working on the solution of the bug. Since, the more clearer in reporting the more faster the bug will be fixed.

在应用程序团队中，我们经常把客户bug扩散到工程中去。我所学到的教训是，报告bug所付出的努力对于解决bug非常重要。因为，bug报告得越清晰，bug就修复起来越快。

So here we go...

好了，看下面的tips...

Tip 1: Engineer is not a Bad Person who Planted the bug | 工程师不是制造bug的坏人

Seriously, The engineering department/engineer did not plant the bug intentionally, so when you come across a bug and are in a situation to report it,  think that as challenge that is facing the engineer “and” yourself. Both of you are a team in resolving the bug. Just this thought process will make you more co-operative. Try not to think that the solving the bug is 100% burden on the engineer. As a reporter of the bug, you too have good amount of stake in solving the bug.

老实说，工程部门/工程师并不是有意要制造bug。所以，当你遇到一个bug并打算报告的时候，不妨认为这是你与工程师共同面临的挑战。你们组成了解决这一问题的团队，这样想的话会让你更愿意参与和合作。尽量不要认为工程师100%对修复bug负责。作为bug的报告者，修复bug你也有责无旁贷。 (P.S. 研发工程师通常不是制造bug的坏人，那些不懂管理的管理者（比如某些官僚作风严重的项目管理人员）通常才是制造bug的罪魁祸首，因为各种考核和过度的push。毕竟（软件）研发是脑力劳动，不是简单的搬砖头。）

Tip 2: Give Detailed Steps | 列出详细的步骤

This one is really critical. Anybody who reports the bug has to describe the steps to reproduce the bug and all of them will. The difference lies in quality of the steps. Lets take an example of two descriptions of the same bug and you decide which one is better (P.S : for now ignore the technicalities )
这一点真的非常关键。任何报告bug的人都必须描述重现bug的步骤,bug描述得好不好，在于每一步的质量。下面给出同一个Bug的两个描述实例，读者不妨看看哪个描述得更好。(注：现在忽略技术细节)

Description 1: 描述1

When There are three "Type A" Devices in a network and one "Type B" Device. When "Type B" Device  tries to join the network ("Type B" Device being Network coordinator), the other devices does not allow the "Type B" Device to join the network and the whole network crashes.
网络中有三个"A型"设备和一个"B型"设备。当"B型"设备(网络协调器)试图连接网络时，其他设备不允许"B型"设备加入，整个网络崩溃。

Description 2: 描述2

1. Connect three "Type A" Devices and 1 "Type B" Device in a Network
2. Power Up all The Devices
3. Issue "Command 1"  in "Type B" Device to Make it as Network Coordinator
4. Type "Command 2" in "Type B" Device’s  Console to get the  number of devices in the Network and observe output as 4.
5. Power Cycle "Type B" Device
6. Type "Command 2" in "Type B" Device’s Console for number of devices in the Network and observe that the output is 0.
7. Expected output in "Step 6" is 4

1. 在网络中接入三个"A型"设备和1个"B型"设备
2. 给所有设备上电
3. 在"B型"设备中执行"命令1"，使之成为网络协调器
4. 在"B型"设备的控制台中键入"命令2"，以获取网络中设备的数量，其输出为4
5. 对"B型"设备进行重启(先断电再上电)
6. 在"B型"设备的控制台中键入"命令2"，以获取网络中设备的数量，其输出为0
7. 第6步的期望输出应当为4

Obviously Description 2 is clear. Here are the reasons..

显而易见地，描述2清晰明了，原因如下：

1. Description 2 actually "has" numbers for each step. Numbering the steps is almost always clearer than non numbered steps.
2. Description 1 just says that the problem is happening, it does not say how to reproduce the problem. Whereas, Description 2 clearly describes how to reproduce the problem.
3. Description 2 has all the three critical parts needed in describing a bug..

• [li]a. Setting the stage for the bug to happen, Steps 1 - 5
• b. Actual behavior of the system, Step 6
• c. Expected behavior, Step 7

1. 描述2实际上每一步都有数字。对步骤进行编号，几乎总是比没有编号的步骤要清晰得多。
2. 描述1只是说了问题正在发生，并没有说明如何重现这个问题。然而，描述2清楚地描述了如何重现这个问题。
3. 描述2完全涵盖了描述一个bug所必需的三个关键部分:
   a. 给Bug的产生提供了演绎的舞台，步骤1 - 5
   b. 系统的实际行为，步骤6
   c. 系统的期望行为，步骤7

more often than not we receive the bug descriptions as in Description 1. Of course, the flip side is too many steps. To me, this is also a kind of deterrent, try to keep the steps to optimum. The worse is, the bug reporter send very lengthy description in the form of Description 1 and gets frustrated that software engineer does not follow his procedure :).
通常地，我们会收到形如描述1中的bug描述。当然，在形如描述2中，提供了太多的步骤描述也是不好的。对我来说，如果我去报bug的话，我会尽力提供更加精简的描述步骤。更加糟糕的事情是，当bug报告者以形如描述1的形式发送非常冗长的描述的时候，软件工程师不能够跟随他的描述过程去理解bug，bug报告者就会感到很沮丧(我滴神啦, 开发人员怎么就看不懂？！我哭...Orz...)。

Tip 3: Report Hardware/Software Version | 报告软硬件版本

Almost always try to mention the version number of the software, hardware or both. In embedded systems its also a good practice that Software Engineering provide a facility to extract the version number during run time . Some kind of console application which prints the version of the software in focus (something like the $uname -r command in Linux)
在报bug的时候，总是需要提供软件版本号，硬件版本号或者软硬件版本号。在嵌入式系统中，软件工程提供了一套在运行期间提取版本号的工具。某些控制台应用程序能够打印软件版本（类似Linux中的uname -r命令）。

Tip 4 : Use Diagrams, Pictures and Videos | 使用图表，图片和视频

When you are describing the bug use Diagrams generously (as the saying goes picture is worth thousand words)  and corollary to that is taking pictures. Now a days its more easier than ever to take pictures and Videos . I am pretty sure most engineers will have the thing called a “Smart Phone” and there is 100% chance that it  has a still/video camera built into it.
恰如谚语所说，一张图片胜过千言万语。当你在描述一个bug的时候，使用图片(就好比拍照)是极好的。而现在，我敢说拍照和录像乃前所未有地容易，因为大多数工程师都拥有一部内置摄像头的智能手机。

Taking pictures maybe more useful if you are reporting a bug in a system that has both hardware/software involved (hardware Setup, connection details etc..).
如果在涉及报告一个跟硬件和软件都相关(硬件设置、连接细节等)的bug时，拍照很可能更加有用。

Tip 5 : One bug, one report | 一次只报告一个bug

I have seen this happening. The bug reporter starts of with the main issue and says “Oh BTW we also see this other issue” or during active debugging phase of the reported bug,  the bug reporter finds another issue and describes it in the same report (in comments section) . There’s nothing confusing than this.  If you are not sure if the bug is same or different, create a new report anyway. If it was indeed the same bug then it can always be marked as duplicate.
我见过这种情况，bug报告从主要问题开始，并说：“哦，顺便说一下，我们也看到了另外一个问题”，或者在报告bug的活跃调试阶段，bug报告者发现了另一个问题，并在同一个报告（注释部分）中描述了它。没有什么比这更令人困惑的了。如果您不确定bug是相同的还是不同的，无论如何请创建一个新的报告。如果它确实是同一个bug，那么它总是可以被标记为重复的bug。

The Bug Database should not be used as dumping ground. Treat it like a database of knowledge. Keep in mind that the current “active bug” is future reference to learn (We all learn from mistakes , don’t we)
Bug数据库不应该当做垃圾场使用，要像对待知识库一样对待它。请记住，当前的"活跃bug"是可以作为未来学习的参考(我们都从错误中学习，难道不是吗？)

Tip 6: Heading be relevant to reported bug | 标题与报告的bug紧密相关

This happens more often if the medium of bug reporting is email. The Heading of the Bug should be relevant to the actual bug description and should remain relevant during the whole life cycle of the bug.This may sound trivial , trust me,  it gets confusing if you have 10 bugs to solve in 20 email threads :)
如果使用电子邮件报告bug的话，这种需求更为常见。bug的标题应该与实际的bug描述相关，并且应该在bug的整个生命周期中保持相关性。这听起来可能不重要，但是请相信我，如果您在20个电子邮件线程中有10个bug需要解决，(不这么做的话)会变得很混乱:)

Tip 7: Document the closure of the bug | 关闭bug有记录

Proper closure statement is needed. This can be a either brief or detailed description of the root cause and the fix that was done to solve the issue.
在关闭bug的时候，适当的描述是必须的。 这可以是对根本原因的简要或详细的描述，也可以是解决此问题所做出的什么样的修复。

There it is. All the above tips are derived from my experience as both bug reporter and as a bug solver. Do you have any more tips? Please feel free to share in the comments section.
好了，以上所有的tips都是源于我的经验，作为一个bug报告人和bug解决人来说。你还有别的tips吗？请在评论中随意地分享。

Happy bugging  to debug :)

最后祝调试bug愉快:-)