如何编写好的错误消息？

Question

虽然这更像是一种书面语言问题而不是编码问题，但程序员必须在客户或其他人不提供复制的情况下这样做。任何错误消息的例子，无论好坏，都欢迎指出。

我进行了简短的搜索，找不到欺骗线程。好的，有它。谢谢，全部。

Answer 1

• 道歉。
• 说出了什么问题。
• 说出如何解决它。
• 礼貌。
• 该消息应该措辞，以便应用程序承担该问题的责任。永远不要责怪或批评用户或让他们认为这是他们的错。

例：
“抱歉，该文件无法打开。请检查该文件是否已被其他程序打开，然后重试。”

如果有其他细节会吓到用户，例如错误编号或其他只有开发人员会理解的内容，请不要显示它们。将它们写入日志文件，或者有一个可以按下的详细信息按钮来访问它们。

我假设您正在谈论在消息框或屏幕上向用户显示错误消息。

Answer 2

您是指面向用户还是管理员/开发人员的日志文件？

我认为这些很重要，一般来说：

• 时间戳
• 严重程度
• 出错
• 回答“我是否需要采取行动？”的问题。和“如果是这样，采取什么行动？”
• dev-level detail（不突出，如果面向用户）
• 一致的格式和条款

我认为所有这些都很重要，但突出性将根据受众而改变（正如dmckee指出的那样）。另一个提示（一般）是回答5 W（谁，什么，等等）

Answer 3

我在一家软件安全公司工作，所以我的答案可能与上述一些答案有很大不同。

面向用户的好消息是：

在通用和特定之间取得平衡 - 您希望为用户提供足够的信息以便他们纠正错误并继续前进，但请记住，攻击者可能会使用这些相同的错误消息来攻击您的网站。一个很好的例子是登录控件，其中返回错误消息“用户joe的密码不正确”或“此系统中不存在用户joe”这告诉攻击者他们正在发现正确的用户。当你没有用户名或密码时，这就是成功的一半。

告诉用户出了什么问题 - 再次在通用和特定之间取得平衡。用户永远不需要看到ODBC错误消息，但是他们知道错误是您的错误并且他们应该在几分钟内再试一次可能会有所帮助。 告诉用户他们可以做些什么来帮助 - 如果你有一个后端日志系统（你应该）记录你认为有用的一切，然后生成一个你可以提供给用户的ID，以便他们可以给你打电话或发电子邮件给你并告诉你确切的repro步骤。您还可以通过在发生错误时公开错误提交表单来自动执行此操作。

保持一致 - 使用错误查找表来确保所有错误都相同（针对同一问题）并且写得很好。在生产软件中不能容忍错别字，拼写错误和语法错误。

Answer 4

对于最终用户：告诉用户该做什么。如果用户更改了某个输入值，请在5分钟后重试或致电支持部门吗？

Answer 5

好的错误消息有三个部分：

1. 问题 - 说明发生了错误;
2. 原因 - 解释导致问题的原因;
3. 解决方案 - 解释如何解决问题。

如果您正在编写或查看错误消息，请首先关注写下这三点。即使消息非常长，也不要在第一次写入时担心。您可以随时返回并简化它。

但事实恰恰相反。很难将一条小信息整形成一条清晰解释问题，原因和解决方案的信息。您将不断编辑您的想法以确保消息保持较小，并且在某些时候您将被阻止。 是的，我已经多次经历过这个问题，所以我知道它有多难。

确保您的消息包含所有这三个部分后，是时候进行审核了。您需要对其进行编辑以确保它：

1. 以用户为中心 - 避免使用行话和言语让观众难以理解;
2. 直接 - 正如William Strunk所说，“以正面形式发表声明。避免驯服，无色，犹豫和不承认的语言“;
3. 忽略不必要的词语 - 剪切，剪切，剪切。

如您所见，这个框架很简单，不需要太多考虑。

来源：

• http://www.joaofn.com/post/how-to-write-error-messages/
• http://blogs.msdn.com/b/brada/archive/2004/01/28/64255.aspx
• http://msdn.microsoft.com/en-us/library/dn742471.aspx

Answer 6

显然，错误预防是最好的。始终为用户提供足够的提示以成功完成任务（即解释数据输入字段上所需的格式）。但是，“犯错误是人......”（通过将可用性原则应用于Web应用程序中的错误）宽恕是目标。

错误消息有三个基本功能：

<强> 1。注意 - 首先，为了确保有效性，用户必须看到它

• 颜色（红色）
• 字体（大小，重量）
• 位置（页面顶部，提示框）
• 焦点（！符号，输入框轮廓）
• 一致性（在整个应用程序中使用类似的错误消息格式）

<强> 2。描述错误 - 告知用户出现了什么问题

• 使用用户理解的简明语言
• 使用客观的声音，不要责怪用户
• 简明扼要

第3。建议恢复 - 提供有用的建议来修复错误并继续

• 保留用户目前已完成的任何内容
• 减少纠正所需的工作
• 对于登录用户，允许在超时时重新进行身份验证

所有这一切，我希望能够编写更详细的内容，特别是有关错误消息的好坏示例。

Answer 7

对于已经说过的话我会补充说：

• 不要提供任何可能存在安全风险的消息，例如密码等。这对于Web应用程序尤其重要，因为这些内容尚未通过反编译提供。
• 如果您还不是一个强迫性的语法和拼写专家，请将所有用户可见文本校对。

Answer 8

要编写好的错误消息，您需要考虑每个受众。一旦了解了受众，就可以更轻松地设计错误消息。

首先，最终用户消息的要求：

• 想要执行任务
• 想要了解解决方案，而不是问题
• 实际上并不想查看或阅读错误消息。

接下来，支持技术人员消息的要求：

• 想要积极主动，而不是被动反应
• 不想遇到“砖墙”问题
• 不想被消息淹没。

最后，支持开发者消息的要求：

• 想要使用代码的简单心理模型
• 期待您的组件“正常工作”
• 如果不起作用，则需要有用的信息。

对于最终用户来说非常糟糕但对开发人员来说可能是合理的错误消息示例是“延迟缓存与出站标头冲突”。 ： - ）

Answer 9

错误消息应该：

• 具体说明导致错误的原因。
• 提供纠正错误的建议。
• 不要使用混淆普通用户的词语。

从语音的技术支持角度来看，错误消息的独特性也很重要。如果用户可以通过六种不同的方式生成相同的“文件无法打开”错误，则技术支持人员很难确切地知道用户正在做什么。因此，错误消息对于每种不同类型的错误应该是唯一的，如果可能的话，提供错误代码或数字，以便支持人员知道在哪里查找问题。

我们发现当错误消息包含错误代码时，它有助于技术支持。当用户向支持人员报告错误消息时，他们经常混淆或错误报告口头错误消息。但是，如果邮件中包含错误编号，则他们非常擅长报告确切的错误，例如“我在尝试打印报告时遇到了8512错误。”

如果可能，它还有助于记录错误。很多时候，用户在尝试特定操作时会报告错误，但他们不会完全记住错误是什么。如果有技术支持人员可以查阅的错误日志，则可以更容易地确定问题。

Answer 10

通常值得指出问题的常见原因，因为这将有助于99.9％的错误用户。

例如，我们有两个初始化问题的方向。一个捕获配置异常，指出：

“发生了已识别的异常。这可能是配置问题”

和另一个出乎意料的：

“发生意外错误。”

然后根据设置（开启或关闭开关），我们可以输出开发信息或更多最终用户友好信息。

Answer 11

错误消息适用于最终用户以及必须维护代码的用户

首先是最终用户，告诉他们该怎么做。这可以简单地按Enter键继续，再次尝试，关闭并重新启动，重新启动PC。

对于维护者来说，尽可能多地包含有关错误的信息。永远不会太多。我个人更喜欢这样的日志文件而不是错误消息。更好的方法是为最终用户提供一种方法，通过电子邮件向您发送应用程序中的日志内容。

Answer 12

如果您可以告诉用户该做什么，请考虑以编程方式进行。在我看来，只有在程序对如何操作有疑问时才会出现错误消息。想想你为什么决定失败：也许没有责任去尝试和恢复？也许用户可以更容易地做到这一点？也许用户必须决定采取哪种解决方案？也许您认为它永远不会发生（在这种情况下不要忘记告诉用户联系支持人员或程序员）？

可能会损害我的神经系统的一件事是当错误消息使用单词OR时。 “文件未找到或没有权限或磁盘已满或您的狗头疼或者......”用户确实需要知道发生了哪一个可能的错误原因。程序员请在错误消息中避免使用OR。

不要将错误消息复制到代码的不同位置。如果用户在您的程序中看到该消息并发送反馈，那么更幸运的情况是您可以了解您的错误消息的含义。不太幸运的情况是，你至少可以grep整个源代码并找到程序崩溃的地方。如果您在多个地方找到相同的消息，则无法自助。

哦，不要忘记提及可能的后果：“松鼠预防系统退出工作。存储在硬盘上的任何东西都可能被松鼠随机修改。” “松鼠预防系统退出工作。相反，通用预防框架将阻止松鼠。”严重程度有所不同。

Answer 13

请记住，最终用户并不关心技术细节。只有它是否有效。当它不起作用时，他或她只关心它对他们想要做什么的影响。有用的错误消息应该集中在 what 上，而不是为什么。

Answer 14

这里可以注意到一些不同的背景（虽然我确信这已被反复提及）：

1）如果我们谈论的网站必须提供“哎呀，发生了一些不好的事情”的消息，那么应该有简单的语言告诉用户发生了错误，请再试一次，如果还有问题请联系支持blah blah blah ...

2）如果我们正在谈论记录代码中为系统管理员和开发人员读取的异常，那么事情变得更多的是将异常的消息和堆栈跟踪记录在日志文件，电子邮件中，或者事件查看器，以便可以根据有人对此的紧急程度进行不同的处理。

3）如果我们正在讨论为异常编写消息，那么我的建议是要清楚地注意到满足哪种错误条件，例如：是否存在空引用，其中不应存在或存在更糟糕的情况，例如应存在的文件，以及错误的严重性，例如：应用程序可以继续运行，还是应该在这种情况下退出错误页面。

Answer 15

从用户的角度出发。