文档化流程
在任何编程语言中，创建易于维护的代码的一个重要部分是确保它也有良好的文档记录。
良好的文档有多种用途
- 虽然在构建流程时一切可能看起来都很明显，但当您以后再回来查看时，您未来的自己会感谢您为细节提供了一些描述。
- 如果您与他人共享流程，这将有助于他们理解它的功能和工作原理。
- 如果一个流程提供了外部 API，您会希望文档化该 API 应如何使用——需要哪些属性或参数。
- 当您编写文档时，写出行为的过程很可能帮助您发现可以改进的部分。
在像 Node-RED 这样的可视化编程环境中，文档可以有多种形式。
- 可以在工作区中读取流程，以查看事件的逻辑流。您应该确保每个节点的目的都易于识别，并且它们布局良好，以尽量减少导线的交叉。
- 组可用于识别流程的离散部分。
- 将常用部分移至子流程有助于降低流程的视觉复杂性。
- 可以在节点、组或选项卡级别添加更完整的文档
布局流程
本指南的流程结构部分探讨了如何安排流程的逻辑组件。本节考虑流程布局的视觉外观。
目标是使其易于跟随流程，而无需在工作区中跳来跳去，或跟随多条相互交叉并显得缠结的导线。
提供最佳易读性的方法是尽可能将每个处理单元保持在一条水平线上。编辑器默认将节点吸附到选项卡上的网格的行为有助于保持它们对齐。
将流程按水平行对齐
如果一个节点有多个输出端口，垂直对齐分支流程可以方便地比较和对比这些流程。
对齐分支流程
当一个流程变得太长时，垂直排列一些节点可以起到很好的效果。在下图中，一些节点被垂直排列，以暗示它们之间的关系。如果能够直观地看出整个流程由哪些较小的部分组成以及它们如何相互关联，那么理解整个流程的性质就会更容易。
垂直对齐长流程的逻辑段
在某些情况下，这些较小的部分可能是移动到子流程的候选者，这将降低流程的视觉复杂性。如果该较小部分可以在流程的其他地方重用，则尤其如此。
命名节点
大多数节点都有一个 name 属性，可用于自定义它们在工作区中显示的标签。这应该用于正确标记流程的关键点。
例如，如果一个 Change 节点有一条规则将 msg.payload 设置为当前时间，其默认标签将是 set msg.payload。这有所帮助，但没有揭示节点的全部目的。一个名为 获取当前时间 的名称会更清晰。
这里需要考虑一个平衡。标签越长，它在流程中需要的空间就越多。标签越短，它能分享的信息就越少。
对于某些节点，完全隐藏标签可能是合适的，以最小化它在流程中使用的水平空间——为其他节点提供更多空间。
除了标签，节点还可以有自定义图标。例如，如果您有多个用于不同类型设备的 MQTT In 节点，自定义图标以匹配设备类型可能会有所帮助。这应该谨慎使用，因为图标是识别特定节点类型的主要方式之一。
为事物选择好名称同样适用于所使用的选项卡和子流程。
对于 Link 节点来说，这一点也非常重要。如果没有设置名称，您在不同选项卡之间创建链接时必须使用 Link 节点的内部 ID。这使得识别正确的目标节点变得困难，并且可能会发生错误。如果您将 Link 节点视为在不同选项卡之间提供 API，那么就需要一个好的命名方案。名称应清楚地标识每个流程的起点和终点。
添加端口标签
如果一个节点有多个输出，如果不清楚在什么条件下消息会从特定输出发送，就很难遵循逻辑。
这时添加端口标签可以帮助记录预期的逻辑。
例如，Switch 节点为其输出提供默认标签，当鼠标悬停在它们上面时会显示。它们可以帮助快速识别流程中每个分支的目的。
虽然在流程本身的上下文中，默认标签可能已足够，但也可以自定义标签以提供更详细的信息。
Switch 节点“外观”选项卡上的自定义输出标签
内联注释
Comment 节点可用于向流程添加内联注释——既包括节点的标签，也包括其描述，当选中时将在信息侧边栏中显示。
通过在页面上缩进流程，您可以表示不同组件的隐含分组。
使用 Comment 节点文档化流程
分组节点
通过将相关节点分组在一起，可以实现对流程更明确的安排。
每个组的背景颜色也可用于突出显示不同类型的组。
分组节点
添加更长的文档
到目前为止讨论的所有技术都与流程的视觉外观有关。为了添加更深入的文档，还需要更多的东西。
每个节点、组和选项卡都可以在其编辑对话框的“描述”选项卡下添加更长篇的文档。此帮助文档可以使用 Markdown 进行格式化，并包含列表、表格和链接。当选择该项时，此文档会显示在信息侧边栏中。
当需要对流程的目的进行更多解释，或者需要描述一些更复杂的逻辑时，这种更长格式的文档很有用。
当流程提供某种外部 API 时，它也很有用——提供其他开发人员使用该 API 所需的尽可能多的细节。
