如何编写不会吸的错误消息

2020年12月30日10:49:21 发表评论 43 次浏览

贾斯汀·富勒(Justin Fuller)

"发生验证错误。"是的谢谢!

即将发布。这是最后一次需要验证的更新, 我收到一条错误消息, 该消息与电梯上的关闭按钮一样有用。

事实证明is验证错误。我输入的内容是重复的。有效, 它已经存在!

知道这一点不是很有帮助吗?

实际上, 在发生错误时通知几件事会很有帮助。我不需要什么都知道编程的历史不会对我有帮助。该消息应该为我提供了足够的信息, 可以解决此错误, 以便我可以完成工作, 回家和与孩子一起玩。

是什么导致错误?

在JavaScript中, 错误对象始终具有名称, 消息和堆栈属性。该名称为你提供了该错误的一览表。堆栈告诉你发生的位置。消息?好吧, 根据一些开发人员的说法, 你不必担心! "堆栈跟踪为你提供了所需的一切。"

请不要成为这些开发人员之一。

有用的错误信息

举起右手, 将左手放在"清洁代码"的副本上, 然后跟着我重复。

"我保证在错误消息中包含足够的细节, 以便将来的开发人员可以轻松地确定出了什么问题以及需要采取哪些措施来解决。"

发生了什么

当警务人员将你拉下车给你罚单时, 它会显示"不良驾驶"吗?没有!它说你在每小时25英里的学区中以每小时65英里的速度行驶, 通过了一辆停下来的公共汽车, 四年来没有对你的汽车进行检查!当然, 你将入狱, 但至少你知道为什么.

因此, 来自较早版本的错误消息不应为"发生验证错误", 而是:

Unable to save model "user" because the property "email" with value "JustinFuller@company.com" already exists.

代替一个简单的错误提示" Invalid option", 使用:

The option "update" is not valid. Valid options include "upsert", "get", and "delete".

这些更新的错误消息试图帮助我们了解原因, 从而使我们着手解决方案。

它可能如何发生

既然错误描述了到底出了什么问题, 那么该是时候帮助跌跌撞撞地陷入困境的那个可怜的灵魂重新站起来的时候。小心点正确完成后, 你似乎就在期待时间的流逝, 这可能会导致不幸的事件发生。你将与未来的开发人员(也许是你自己)在一起, 告诉他们一切都很好, 你将共同完成任务。

你将从解释发生的事情开始。

对于具有先决条件步骤的任何内容(例如配置或验证), 你可以建议验证该步骤是否已完成。如果你的错误消息过长, 请不要担心。最好提供太多的信息, 而不要提供太多的信息。

我将为较早的示例添加更多细节:

The option "update" is not valid. Valid options include "upsert", "get", and "delete". If you expected "update" to be an option, you must first export it from the file: "./src/controllers/index.js".

现在你正在预料这将如何发生:开发人员可能只是忘记了导出新选项。该错误提示该步骤。现在, 你已经显示了两种可能的错误原因;第一个是可能的错字(这里是有效的选项), 第二个是配置错误(应在此处导出)。

React库在预测错误如何发生方面做得非常出色。它们并不能解决所有极端情况, 但确实可以为最常见的错误提供有用的提示。例如, 你不能使用该功能reactDom.renderToNodeString()在浏览器中, 因为节点流在那里不存在。因此, React为你提供了有关它如何发生以及如何解决的建议:

ReactDOMServer.renderToNodeStream(): The streaming API is not available in the browser. Use ReactDOMServer.renderToString() instead.

可能有其他方式发生该错误, 但他们猜测最常见的原因是renderToNodeStream在浏览器中被调用。

相关资料

在编写错误消息时, 你必须记住, 应用程序很少一次只做一件事。因此, 当发生错误时, 要在那个时候找到应用程序的状态是一个挑战。因此, 捕获相关数据并将其转发给开发人员非常重要, 这样他们才能查明原因。

在第一个示例中, 我添加了短语:

The property "email" with value "JustinFuller@company.com" already exists.

这是非常有用的, 但可能不切实际。对于每种数据变化, 创建自然的语言错误可能会花费过多的精力或时间, 或者在某些情况下, 我们可能只是将失败传递给我们自己的控制之外, 因此剩下的唯一选择就是给出良好的描述并包括安全打印尽可能多的相关数据。

选择哪种数据可以安全打印是很棘手的:如果你确切选择要包括的属性, 则每次有新属性时最终都要修改列表, 或者更糟的是, 你忘记了它, 并且在需要时它不会显示;另一方面, 你可以删除已知不安全的属性, 但是在这里你可能会冒险添加新属性而忘记将其排除在外, 从而导致敏感数据泄漏。你必须运用自己的判断力并考虑公司规则。你的软件是否处理不应写入非加密目标的极有价值的个人数据?粗心地注销每一个导致错误的对象可能会使你被某些工作解雇, 而在另一些工作中则是标准操作程序。因此, 请使用常识并当心!

意外错误

当你不知道是哪个属性或操作导致错误时, 可以通过两种方式包含相关数据。

如果你打算让人类读取错误, 并且将数据正确地放在消息中, 则应该使用第一个:上报用户:{" email":" justinfuller@company.com"}时收到错误:"为user.email找到重复的条目"。这种错误样式有其缺点, 例如将整个对象放入错误消息中, 而该错误消息可能会意外发送到某个地方。但是, 如果你知道它是安全的, 则此样式的优点是可以提供有关情况的完整详细信息。

在其他情况下, 你可能不希望数据泄漏到日志文件或API响应中。你可以提供参考ID, 可以在以后手动或自动参考数据的时间戳, 或者提供其他一些属性, 使开发人员可以跟踪引起错误的讨厌的数据点。

预期错误

我将是第一个承认我容易犯简单错误的人。我键入" upswert"而不是" upsert";我键入" npm tes"而不是" npm test"。因此, 当我收到一条错误消息:

Unknown command, "npm tes". Did you mean npm test?

当开发人员为此做好准备时, 他们显然盯着未来, 看到有人会打错字, 或者也许他们只是知道人类很容易犯傻错误。

只要流程中的某个步骤可能出现可预见的错误, 你就有机会就错误的原因和解决方法准备明确的指导。

解决问题的步骤

对于某些错误, 有可能为错误提供解决方案, 而不仅仅是报告它已发生。有时候, 这很容易, 例如前面提到的, 我们在不小心输入" update"而不是" upsert"之后显示了正确的选项。有时, 你需要付出更多的努力来为用户提供足够的信息来纠正他们的错误, 例如, 如果你检测到递归依赖项, 则需要告诉他们循环在哪里, 以及他们必须怎么做才能删除它。

不会出错的错误

因此, 你想提供有用的错误消息吗?在你编写的下一个错误中, 尝试包括对发生的情况, 可能发生的情况, 可以安全包括的所有相关数据以及可能有助于解决问题的所有步骤的完整说明。

大家好, 我叫Justin Fuller。我很高兴你阅读我的帖子!我需要让你知道, 我在这里写的所有内容都是我个人的看法, 并不以任何方式代表我的雇主。所有代码示例都是我自己的, 并且与美国银行的代码完全无关。

我也很想收到你的来信, 请随时与我联系领英, Github, 要么中。再次感谢你的阅读!

一盏木

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: