Hi to all,
I remember some hard discussions about adding comments to rule machine or not. They are finally there and I'm generally very happy with them. Personally, I would have preferred that the the word 'Comment:' is not shown, but I can live with it 
Here is an example on how I want to use them for my planned vlog to make understanding easier for the watchers. I know that I use them here excessively, far more than for my personal needs. I would be happy to hear your comments.
As long as we don't use the word "comment" 
Are you looking for comments on your rule itself or on your use of comments? 
(The latter is entirely a personal choice, and I've never used them but don't see an issue as long as they fill whatever purpose you're hoping to get out of them...if you're talking about the rule itself, we can't say more without seeing your trigger, but making reasonable guesses, it should be noted that you're not really checking if the door stays open for a minute but rather if it just happens to be open one minute after any time it was opened. In some cases, this may not be the same, though you may not care that much about the distinction in real-world use. You also appear to be running the same rule actions at the end regardless of the variable state, so I'm not sure what the conditional is for.)
My question was more about the usage or presentation of the comments. Supposing you are a novice to Hubitat and someone explains rules in a video blog to you, do you think my comments can make understanding easier for the follower ?
The goal of the rule is quite easy. The house or terrasse doors are doors that often are opened just to go through and are closed afterwards. In my previous rules this triggered always the thermostat heads (Spirit) to close the valve and to open it again in a short interval (procedure initially foreseen when windows or doors stay open). At first sight, this seems to do no harm, but if the doors are often used along the day this considerably drains the batteries of the thermostat heads as the motor turns every time. The intention of this rule is to not trigger immediately, but only to notice the opening and to check after a minute if the door is still open. If so, close the valves, if not, do nothing.
Not really. The entire rule is triggered by a change in the state of the door contact.
The first run of the follow up rule is triggered when the door is open but was closed a minute ago and the second is triggered when the door is closed but was open a minute ago. So only when a change happened. If the door is closed and was closed nothing is run. And yes, the follow up rule is the same. That one handles the settings ON/OFF and setpoint of the thermostat heads depending on different conditions like Heating ON/OFF, Holliday ON/OFF, contacts open or closed, outside temperature and so on.
Not sure this is clear...
Ah, I see the difference with the conditionals now that I missed before (I was confusing the state of the variable with the actual device).
As for the Rule comments themselves, if you're just wondering whether the comments make sense to other people, then I suppose they do to me. Personally, when I write rules for people, I usually just end up explaining things elsewhere anyway; writing in-line comments in the rules takes up more space so makes the rule harder to read and probably takes longer to do...but I guess whatever works for the other person is best.
And not that you were asking for comments on the rule itself, but if you just want to only do things if the door stays open for a minute, a rule like this should do the same thing and is much simpler to write:
Trigger: Door open
Actions:
Wait for condition: Door open --> duration 0:01:00
IF (Heating is on) Run Actions: Other Rule
That being said, there might be a bug with "Wait for condition" plus "duration" in 2.2.8, so this might not currently work as you expect, and it might need to be written as something more like this instead. (EDIT: Nevermind, that does not affect this particular action, just additional waits that may come after it--so either way should work, and I'll leave both here). Unlike the above (which requires Rule 5.0, new in 2.2.8), this example will also work in Rule 4.1:
Trigger: Door *changed*
Actions:
IF (Door open) THEN
Wait for event --> elapsed time 0:01:00
IF (Heating is on) Run Actions: Other Rule
END-IF
The second rule takes advantage of the fact that a re-trigger (so the door changing) cancels any "Waits," and it will only get re-scheduled if the door is opened again. In the first rule, the new "duration" option with "Wait for condition" should proceed only if the door stays that way for that long, which is also why it doesn't need to trigger on either event like the second rule.
If I was going to teach or show someone what I was doing, I would think that you would break it down further or annotate things using software or use a different font/highlight things instead of adding inline comments.
In my opinion, I don't think throwing those comments in there helps a novice. And I think it adds clutter, and I could even see someone inserting needless comments just to follow the example. But different people learn different ways, so hard telling what an audience would like.
Instead of opening and closing the comment with the full broken line, I'd enclose the line or section the comment applies to, with the comment itself enclosed along with it, Put Comment: [comment body] all on one line
Thank you for this suggestion. I never used Wait for event. If I understand well, if the door is closed nothing will happen to start heating again. So the same will ne needed for closing the door ?
I tend to agree with @neonturbo, other more verbose and targeted notes would help those trying to learn how rules, and the HE platform more generally, works, and there are more appropriate tools or mediums to capture this information.
Without having seen the comments option until now, my take on it would be it can help to provide queues to the developer or the person maintaining the rule for what the intention was for the rule and why certain conditions or actions were chosen over alternatives, particularly where it is not obvious to look at. Certainly this information would also be useful to new users, but there can be concepts that are not easily or succinctly able to be captured in text-based comments.
Just my opinion....
Thank you for all your replies. I agree that the comments are not the best way if they are used as the only help. In a video blog, code fragments will be highlighted and explained. The code (as picture) will be provided to the follower and the comments are used as a help to remember what this fragment does when the code is read later. Flow diagrams and many other features will naturally be used too. My vlog is only planned to come in some month, so I still have time to think again about it and take into consideration all your valuable arguments.
Download the Hubitat app
