From 6fbc650a5d3a546f60dd96b91471f434eb0268e5 Mon Sep 17 00:00:00 2001 From: LEEHYUKJOO Date: Fri, 1 Feb 2019 10:38:28 +0900 Subject: [PATCH 1/2] Pages to discuss chapter composition of flow dev guide --- _includes/practice-toc.html | 14 ++++++ docs/index.html | 7 +++ docs/practice/designing.md | 65 +++++++++++++++++++++++++++ docs/practice/implementation.md | 25 +++++++++++ docs/practice/index.md | 12 +++++ docs/practice/multiple-developers.md | 19 ++++++++ docs/practice/non-functional.md | 37 +++++++++++++++ docs/practice/readability.md | 41 +++++++++++++++++ images/guide-practice.png | Bin 0 -> 4992 bytes 9 files changed, 220 insertions(+) create mode 100644 _includes/practice-toc.html create mode 100644 docs/practice/designing.md create mode 100644 docs/practice/implementation.md create mode 100644 docs/practice/index.md create mode 100644 docs/practice/multiple-developers.md create mode 100644 docs/practice/non-functional.md create mode 100644 docs/practice/readability.md create mode 100644 images/guide-practice.png diff --git a/_includes/practice-toc.html b/_includes/practice-toc.html new file mode 100644 index 00000000..dd605140 --- /dev/null +++ b/_includes/practice-toc.html @@ -0,0 +1,14 @@ + diff --git a/docs/index.html b/docs/index.html index e3921705..57828176 100644 --- a/docs/index.html +++ b/docs/index.html @@ -46,6 +46,13 @@

API Reference

Admin, runtime and storage APIs

+ diff --git a/docs/practice/designing.md b/docs/practice/designing.md new file mode 100644 index 00000000..f56583df --- /dev/null +++ b/docs/practice/designing.md @@ -0,0 +1,65 @@ +--- +layout: docs +toc: practice-toc.html +title: Designing a flow +--- + +### Development steps + +*If a project needs complicated logic, it is better to design flow before starting development. After that, you create flows based on the flow design. In this subsection, we show an overview of whole recommended steps of design and development.* + +* *Design* + - *Flow structure* + - *Message* +* *Implementation* + +### Designing flow structure + +*As the size of flows in a tab gets larger, it can be difficult to recognize a function of each flow within a tab. To improve reusability of flows, it would be better to decide the responsibility of flows within each tab and the scale of one tab. To do this, it is helpful to sort out what kind of things, people, work, rules are in the target domain of the application, and relationship of them.* + +### Designing messages + +*There are risks that multiple nodes have dependencies by messages passing the nodes.* +*For other developers to reuse flows, it is important to design messages so that dependencies get to be relaxed. This chapter proposes a guide about designing message.* + +*We have already written actual contents on [here](https://github.com/node-red/node-red.github.io/wiki/Flow-Guideline-Contents).* + +#### Designing key-value structure of `msg` + +*`msg` is a JavaScript object that contains a key-value structure like JSON. While a `msg` transits across multiple nodes, the nodes use some keys and values of the `msg`. If two or more nodes of them use the same key for different their own purposes, preparing `msg` for input of the nodes is so difficult.* + +*Therefore, policies of key-value structure are needed and this subsection describes it as such as followings,* + +* *Top-level keys of `msg` are used to control the functionality of node* +* *`msg.payload` is used as input parameters of a process of a node* + +#### Keeping properties + +*In the case of using function node, you can prepare output messages by creating new `msg` objects. However, the output messages may not have some properties that the input message has. This means that properties that should be kept in your flow has lost. Since this can be a cause of serious bugs, preparing output messages based on an input message is better, instead of creating new `msg`.* + +#### Add tag into `msg` to distinguish a node that sent the `msg` + +*[Tips] If it is needed that a (latter) node executes a different process depending on a (former) node that send `msg`, former node adds tags describing the former node itself. With the tag, the latter node decide the process to execute.* + +#### Using persistent storage outside of Node-RED + +*If you handle the large amount of data, it is **not** recommended to set the data into `msg` since `msg` can be a cause of a lack of memory. Instead, you had better put the data on a persistent storage that is in outside of Node-RED and use reference to the data for handling the data.* + +#### Processing in order of arrival of messages + +*Since Node-RED (JavaScript) processes asynchronously, a node cannot assume that it executes process for arrival `msgs` by the order of arrival.* + + \ No newline at end of file diff --git a/docs/practice/implementation.md b/docs/practice/implementation.md new file mode 100644 index 00000000..7a0db6c4 --- /dev/null +++ b/docs/practice/implementation.md @@ -0,0 +1,25 @@ +--- +layout: docs +toc: practice-toc.html +title: Implementation of flow +--- + +### Cooperation between flows + +*One application may be constructed by integration of small flows that provide small functions. Since each small flow may be created by a different team, deciding how to integrate the small flows is important for smooth collaborative development.* + +*Http in/out/request nodes are useful for the integration. However, if you do not want to expose endpoints of small flows, you can make sub flows from the small flows and create an additional flow to integrate sub flows.* + +### Managing environmental variables + +*Global context can be used as an environmental variable of flow execution. However, if you use the global context in various nodes, identifying dependencies between nodes becomes a hard work, and it can lead to bugs. To minimize the dependence on the global context, it is necessary to make it easier to see where the global context is used.* + +### Flows that can have adverse effects + +*With Node-RED, even non-programmers can easily enjoy coding. However, Node-RED (as of 0.19.5) does not strict restrictions on creating flows and debugging tools such as a lint, you can easily create dangerous flows that can cause bugs. In particular, it is also possible to lead to resource exhaustion of Node-RED engine.* + +*This chapter shows certain cautions and principles not to create such dangerous flows.* + +### Error Handling + +*To create reliable flows, error handling is essential. This chapter explains its implementation method and arrangement of error handling flow to easily distinct between nominal flow and anomaly flow.* \ No newline at end of file diff --git a/docs/practice/index.md b/docs/practice/index.md new file mode 100644 index 00000000..ee707290 --- /dev/null +++ b/docs/practice/index.md @@ -0,0 +1,12 @@ +--- +layout: docs +toc: practice-toc.html +title: Introduce +--- +*This guide is for who understands the basic fuctinality and want to develop more clear and reusable flows. If you thik that you are beginner, please read **[User Guide](https://nodered.org/docs/user-guide/)** and **[Cookbook](https://cookbook.nodered.org/)** first.* + +*In Node-RED, users can create flows easily and ad hoc. However, if you want to create more reusable and readable flows, some tips, practices and know how may be needed. Therefore, we would propose to create a new flow development guideline page to show such knowledge on Node-RED official page. We believe this page is useful for most Node-RED users.* + +*Before adding guideline to the Node-RED official page through a pull request, we would like to discuss contents and where to place it with somebody who are interested in this guideline. This wiki page is for discussing them.* + +*At first, we’d like to show a contents list and where to place it on Node-RED official page. After that, we will write the actual contents and discuss it with Node-RED community because we would reduce unnecessary work.* \ No newline at end of file diff --git a/docs/practice/multiple-developers.md b/docs/practice/multiple-developers.md new file mode 100644 index 00000000..35918ddb --- /dev/null +++ b/docs/practice/multiple-developers.md @@ -0,0 +1,19 @@ +--- +layout: docs +toc: practice-toc.html +title: A project with multiple developers +--- + +*When multiple developers join the development, you may need development standards and environments that can facilitate collaborative development. This chapter describes about them.* + +### System and development environment + +*The project feature of Node-RED can be linked with Git and you can manage the version of flows. It is recommended to use Git remote repository such as GitLab or GitBucket for sharing flows and projects among members. This chapter describes the development environment using Git.* + +*In detail, we plan to describe followings.* + +* *Configuration of development environment* +* *Procedure of developing* +* *Steps of release* + +#### Management of flow with git \ No newline at end of file diff --git a/docs/practice/non-functional.md b/docs/practice/non-functional.md new file mode 100644 index 00000000..db3491cd --- /dev/null +++ b/docs/practice/non-functional.md @@ -0,0 +1,37 @@ +--- +layout: docs +toc: practice-toc.html +title: Responding to strict non-functional requirements +--- + +*Node-RED does not strongly focus on applications with strict non-functional requirements.* +*However, there are cases that it is necessary to satisfy high level non-functional requirements.* +*This chapter explains techniques and others to satisfy non-functional requirements.* + +### Precautions due to single thread + +*If a node takes long time for execution, the process of the entire Node-RED instance stops.* +*Therefore, it is advisable to outsource the processing with running other services.* + +### Sequential guarantee + +*Node - RED does not guarantee the arrival order of messages. Therefore, it is better to design related messages in a format expressing the order relation of messages. (Separated message format)* + + \ No newline at end of file diff --git a/docs/practice/readability.md b/docs/practice/readability.md new file mode 100644 index 00000000..e7f5b4c8 --- /dev/null +++ b/docs/practice/readability.md @@ -0,0 +1,41 @@ +--- +layout: docs +toc: practice-toc.html +title: Improving readability +--- +### Align nodes + +*As the size of the application increases, the process of flow will become complicated, which decreases readability and understandability. One of the key points to improve readability and understandability is a proper node alignment such that flows of one function are adjacent to each other. This chapter shows effective node alignment.* + +### Naming rule + +*Name of nodes, tabs and subflow is important for readability and reusability of flows. This chapter presents some effective naming rules of them.(italic)* + +### Using proper nodes + +*Each node can be used flexibly. For example, a function node can cover the same function of Change node, Switch node and so on. However, using a proper specialized node for your objective contributes improving understandability of your flows. This chapter introduces the roles and usage of core nodes such as **Change, Switch, Template, Link, HTTP**.* + +*The **Function** node and **Exec** node are useful for JavaScript and other language developers because they can write JavaScript codes and commands directly. However, heavy use of them makes understanding flow difficult for other developers. This chapter describes a caution of these nodes and shows examples of alternative methods against Function node and Exec node.* + +#### Link node + +*You can divide the flows when it be too long by using Link node. And it allows you create flows accroding to the size of the display and makes the layout clean.* + +### Changing icon + +*When the same kind nodes are in the flow (e.g. a case that managing a large number of devices with MQTT nodes), it is difficult to distinguish nodes. But, it can be solved by designating different icons for each node. This chapter introduces the procedure for changing the icon and some Use Cases.* + +### Comment + +* *Comment on tab* +* *Comment on flow (Comment node)* +* *Comment on subflow* +* *Logging strategy* + +### Refactoring + +*It is better to check and refactor the developed flows before presenting it to other developers. This section shows refactoring points such as followings,* + +1. *Coding Style* +2. *Flow implementation* +3. *Readability and reusability* \ No newline at end of file diff --git a/images/guide-practice.png b/images/guide-practice.png new file mode 100644 index 0000000000000000000000000000000000000000..670b290b9824a1c7d182add7975309767c795f4f GIT binary patch literal 4992 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 Date: Mon, 4 Feb 2019 10:37:44 +0900 Subject: [PATCH 2/2] Modified pages to discuss chapter composition --- docs/practice/designing.md | 8 ++++---- docs/practice/implementation.md | 8 ++++---- docs/practice/index.md | 6 +++--- docs/practice/readability.md | 6 +++--- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/practice/designing.md b/docs/practice/designing.md index f56583df..eb090e51 100644 --- a/docs/practice/designing.md +++ b/docs/practice/designing.md @@ -19,7 +19,7 @@ title: Designing a flow ### Designing messages -*There are risks that multiple nodes have dependencies by messages passing the nodes.* +*There are risks that multiple nodes have dependencies by messages passing through nodes.* *For other developers to reuse flows, it is important to design messages so that dependencies get to be relaxed. This chapter proposes a guide about designing message.* *We have already written actual contents on [here](https://github.com/node-red/node-red.github.io/wiki/Flow-Guideline-Contents).* @@ -28,7 +28,7 @@ title: Designing a flow *`msg` is a JavaScript object that contains a key-value structure like JSON. While a `msg` transits across multiple nodes, the nodes use some keys and values of the `msg`. If two or more nodes of them use the same key for different their own purposes, preparing `msg` for input of the nodes is so difficult.* -*Therefore, policies of key-value structure are needed and this subsection describes it as such as followings,* +*Therefore, policies of key-value structure are needed and this subsection describes it as followings,* * *Top-level keys of `msg` are used to control the functionality of node* * *`msg.payload` is used as input parameters of a process of a node* @@ -43,9 +43,9 @@ title: Designing a flow #### Using persistent storage outside of Node-RED -*If you handle the large amount of data, it is **not** recommended to set the data into `msg` since `msg` can be a cause of a lack of memory. Instead, you had better put the data on a persistent storage that is in outside of Node-RED and use reference to the data for handling the data.* +*If you handle the large amount of data, it is **not** recommended to set the data into `msg` since `msg` can exhaust available memory. Instead, you had better put the data on a persistent storage that is outside of Node-RED and use reference to the data for handling the data.* -#### Processing in order of arrival of messages +#### Processing messages in order of their arrival *Since Node-RED (JavaScript) processes asynchronously, a node cannot assume that it executes process for arrival `msgs` by the order of arrival.* diff --git a/docs/practice/implementation.md b/docs/practice/implementation.md index 7a0db6c4..92dbf704 100644 --- a/docs/practice/implementation.md +++ b/docs/practice/implementation.md @@ -10,15 +10,15 @@ title: Implementation of flow *Http in/out/request nodes are useful for the integration. However, if you do not want to expose endpoints of small flows, you can make sub flows from the small flows and create an additional flow to integrate sub flows.* -### Managing environmental variables +### Managing flow parameter -*Global context can be used as an environmental variable of flow execution. However, if you use the global context in various nodes, identifying dependencies between nodes becomes a hard work, and it can lead to bugs. To minimize the dependence on the global context, it is necessary to make it easier to see where the global context is used.* +*Global context can be used as a parameter of flow execution. However, if you use the global context in various nodes, identifying dependencies between nodes becomes a hard work, and it can lead to bugs. To minimize the dependence on the global context, it is necessary to make it easier to see where the global context is used.* ### Flows that can have adverse effects -*With Node-RED, even non-programmers can easily enjoy coding. However, Node-RED (as of 0.19.5) does not strict restrictions on creating flows and debugging tools such as a lint, you can easily create dangerous flows that can cause bugs. In particular, it is also possible to lead to resource exhaustion of Node-RED engine.* +*With Node-RED, even non-programmers can easily enjoy coding. However, Node-RED (as of 0.19.5) does not place strict restrictions on creating flows and does not provide debugging tools such as a lint. Thus, you can easily create dangerous flows that can cause bugs. In particular, it is also possible to lead to resource exhaust of Node-RED engine.* -*This chapter shows certain cautions and principles not to create such dangerous flows.* +*This chapter shows certain cautions and principles preventing from creating such dangerous flows.* ### Error Handling diff --git a/docs/practice/index.md b/docs/practice/index.md index ee707290..891f3562 100644 --- a/docs/practice/index.md +++ b/docs/practice/index.md @@ -1,11 +1,11 @@ --- layout: docs toc: practice-toc.html -title: Introduce +title: Introduction --- -*This guide is for who understands the basic fuctinality and want to develop more clear and reusable flows. If you thik that you are beginner, please read **[User Guide](https://nodered.org/docs/user-guide/)** and **[Cookbook](https://cookbook.nodered.org/)** first.* +*This guide is for developers who understand the basic fuctinality and want to develop more clear and reusable flows. If you think that you are beginner, please read **[User Guide](https://nodered.org/docs/user-guide/)** and **[Cookbook](https://cookbook.nodered.org/)** first.* -*In Node-RED, users can create flows easily and ad hoc. However, if you want to create more reusable and readable flows, some tips, practices and know how may be needed. Therefore, we would propose to create a new flow development guideline page to show such knowledge on Node-RED official page. We believe this page is useful for most Node-RED users.* +*In Node-RED, users can create flows easily and in ad hoc manner. However, if you want to create more reusable and readable flows, some tips, practices and know how may be needed. Therefore, flow development guideline page is intended for gathering such knowledge. We believe this page is useful for most Node-RED users.* *Before adding guideline to the Node-RED official page through a pull request, we would like to discuss contents and where to place it with somebody who are interested in this guideline. This wiki page is for discussing them.* diff --git a/docs/practice/readability.md b/docs/practice/readability.md index e7f5b4c8..b3ad2cd3 100644 --- a/docs/practice/readability.md +++ b/docs/practice/readability.md @@ -9,17 +9,17 @@ title: Improving readability ### Naming rule -*Name of nodes, tabs and subflow is important for readability and reusability of flows. This chapter presents some effective naming rules of them.(italic)* +*Name of nodes, tabs and subflow is important for readability and reusability of flows. This chapter presents some effective naming rules of them.* ### Using proper nodes *Each node can be used flexibly. For example, a function node can cover the same function of Change node, Switch node and so on. However, using a proper specialized node for your objective contributes improving understandability of your flows. This chapter introduces the roles and usage of core nodes such as **Change, Switch, Template, Link, HTTP**.* -*The **Function** node and **Exec** node are useful for JavaScript and other language developers because they can write JavaScript codes and commands directly. However, heavy use of them makes understanding flow difficult for other developers. This chapter describes a caution of these nodes and shows examples of alternative methods against Function node and Exec node.* +*The **Function** node and **Exec** node are useful for JavaScript and other language developers because they can write JavaScript codes and commands directly. However, heavy use of them makes understanding of flow difficult for other developers. This chapter describes a caution of these nodes and shows examples of alternative methods against Function node and Exec node.* #### Link node -*You can divide the flows when it be too long by using Link node. And it allows you create flows accroding to the size of the display and makes the layout clean.* +*You can divide the flows when it become too long by using Link node. And it allows you to create flows accroding to the size of the display and makes the layout clean.* ### Changing icon