文档化流程
在任何编程语言中，创建易于维护的代码的重要部分是确保它也有良好的文档。
良好的文档服务于多个目的：
- 尽管在构建流程时一切似乎都很明显，但当你以后回过头来时，你的未来自我会感谢你提供的一些细节描述。
- 如果你正在与他人共享一个流程，这将帮助他们理解它的功能和工作原理。
- 如果一个流程提供外部 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。
