フローのドキュメント

どのプログラミング言語においても、保守が容易なコードを作成するために必要不可欠なことのひとつは、よくドキュメント化されているかを確認することです。

良いドキュメンテーションは、以下の様な多くの目的のために役立ちます:

1. フロー作成者自身であれば全てが明らかなことに見えるかもしれませんが、いくらかの詳細説明が提供されていることは、将来、後から見返す時に自分にとっても役立つでしょう。
2. もしフローを他の開発者と共有している場合、ドキュメンテーションはフローが何をしているか、またどの様に動作するかを理解してもらうのに役立つでしょう。
3. もしフローが外部へAPIを提供する場合、APIがどの様なプロパティやパラメータを期待するか等、使い方をドキュメント化したいでしょう。
4. ドキュメントとして動作を書き出すことにより、改善点を特定できることがあります。

Node-REDの様なビジュアルプログラミング環境においては、ドキュメンテーションはいくつかの方法があります。

• イベントのロジカルな流れを把握するために、ワークスペース上でフローを読むことができます。各ノードの目的を簡単に把握できる様に、また交差するフローを最小限にする様に、それらを適切に配置します。
• グループは、フローの一部を特定できるようにするために用いることができます。
• 共通で利用する部分をサブフロー内へ移動することで、フローの視覚的な複雑さを減らすことができます。
• より完全なドキュメントは、ノード、グループ、タブに追加できます。

フローの配置

このガイドのフローの構造のセクションでは、どの様にフローのコンポーネントを整えるかについて説明しました。このセクションでは、フローの配置の見た目について考えてゆきます。

ここでの目標は、ワークスペース内を飛び回ることなく、また互いに交差して絡まった様に見える複数のワイヤーを辿ることなく、フローを簡単に辿れる様にすることです。

最も読みやすくする方法は、可能な限り各処理単位を水平に配置する方法です。エディタのデフォルトの動作である「ノードの配置を補助」の機能は、タブ上のグリッドを用いてノードを整理するのに役立ちます。

もし複数の出力ポートがあるノードが存在する場合、後続の複数の分岐フローを垂直に並べることで、フローの比較が容易となります。

フローが長い場合は、いくつかのノードを縦に配置すると良いでしょう。下の図では、いくつかののノードを縦に配置し、それらの関係を表現しています。もし、フローの各部がお互いにどの様に関係しているか視覚的に明らかである場合は、フロー全体の性質を理解しやすくなります。

場合によっては、これらフローの一部は、視覚的な複雑さを減らすために、サブフロー化の対象になることもあります。フローの一部が他の場所で再利用できる場合は、特にこれに当てはまります。

ノード名

ほぼ全てのノードは、ワークスペース上に表示するラベルをカスタマイズするために 名前 プロパティを持っています。これは、フロー内の重要な場所で、適切に名前をつける必要があります。

例えば、Changeノードで msg.payload に現在時刻を格納するルールが設定されている場合、デフォルトで set msg.payload というラベルになります。これはいくらか役に立つラベルですが、このノードの全ての目的を表すものではありません。そのため、 Get current time という名前の方がより的確でしょう。

ここには、考慮すべきバランスがあります。長いラベルは、フローにおいてより多くの場所を必要とします。一方で、ラベルが短すぎると共有できる情報が少なくなってしまいます。

一部のノードにおいては、フローで使用できる水平方向のスペースを他のノードに割り当てるために、ラベルを非表示にすることが適切である場合もあります。

ラベルに加えて、ノードはカスタムアイコンを持つこともできます。例えば、様々なタイプのデバイスからデータを取得するMQTT Inノードが沢山ある場合、デバイスのタイプと一致するアイコンを選択することで、より分かりやすくなります。ただし、アイコンはノードの種類を特定する主な手段であるため、注意してこの機能を利用してください。

適切な名前を選択することは、タブやサブフローについても言えることです。

また、リンクノードにおいても適切な名前はとても重要です。名前が設定されていないと、リンクノードを用いて異なるタブ間でリンクを作成した時に、リンクノードの内部IDを用いる必要が出てきてしまいます。これによってユーザは対象のリンクノードを正しく特定することが難しくなり、間違いが生じる可能性があります。タブ間を接続するAPIの様にリンクノードを用いることを考えている場合は、名前を適切に選択する必要があります。リンクノードには、各フローの開始点と終了点が明確に分かる様に名前を付けるべきです。

ポートラベルの追加

ノードが複数の出力ポートを持つ場合、出力ポートから送信されるメッセージの条件が明確でないと、ロジックを追うのが困難になることがあります。

その時は、ポートラベルを追加することで、ロジックをドキュメント化できます。

例えば、Switchノードでは、出力ポートの上にマウスポインタを置くと、デフォルトで出力のラベルを表示します。この機能は、フロー内の各分岐の目的を素早く理解するのに役立ちます。

デフォルトのラベルでもフロー自身を説明するのに十分な場合もありますが、より詳細な情報を追加するために、ラベルをカスタマイズすることもできます。

インラインコメント

Commentノードを用いることで、フローに対して(本ノードのラベルだけでなく、本ノードを選択した時に情報サイドバーに表示される「詳細」にも)インラインのコメントを追加できます。

複数のフローに対してインデントすることで、異なる部品に対してグループの意味を持たせることができます。

ノードのグループ化

フローのより明示的な配置は、関連するノードをグループ化することで実現できます。

各グループの背景色を用いることで、異なるタイプのグループを強調することもできます。

さらに長いドキュメントを追加

ここまでに説明したテクニックは全て、フローの視覚的な外観と関係するものでした。詳細なドキュメントを更に追加するには、さらに方法が必要です。

ノード、グループ、タブには、編集ダイアログにある外観タブに、長いドキュメントを追加できる機能を持っています。このヘルプはMarkdown形式で記述されるドキュメントのため、リスト、表、リンクを含めることができます。本ドキュメントは、要素が選択された時に情報サイドバーへ表示されます。

この長い形式のドキュメントは、フローの目的をより詳細に説明する場合や、より複雑なロジックを説明する場合に、便利に使えます。

また、外部APIを提供するフローの時は、APIを使用する他の開発者が必要とする詳細を提供するためにも、役立ちます。