Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
http://www.eastgate.com/Tinderbox/forum//YaBB.cgi
Tinderbox Users >> Off The Wall: Feature Ideas >> Commenting Code
http://www.eastgate.com/Tinderbox/forum//YaBB.cgi?num=1420175577

Message started by Ted Goranson on Jan 2nd, 2015, 12:12am

Title: Commenting Code
Post by Ted Goranson on Jan 2nd, 2015, 12:12am

So far as I know, there is no way to comment action code.

I commonly use a code note strategy and do use a key attribute that gives me some place to make notes. But some of my code code well stand being commented as it goes.

So in the future, can we have something like:

// this isn't interpreted.

Title: Re: Commenting Code
Post by Barbara Snyder on Apr 23rd, 2015, 1:04am

+1

In the meantime, I was hoping a dummy "if" expression would work. I put this at the top of my code:

if (1==2) {here are some notes};

But tbx must have gagged on it (instead of just skipping over it) because the rest of the code never got evaluated.

Title: Re: Commenting Code
Post by Ted Goranson on Apr 23rd, 2015, 9:18am

I have been taking a forced vacation from TBx and will get back to it soon. When I do, I will be diving into code once again and am sure that there is some kind of cheap way of dealing with this.

I use a key attribute for code note annotations at the the note level, but it would be nice to have inline comments.

Title: Re: Commenting Code
Post by Mark Bernstein on Apr 23rd, 2015, 11:36am

I'm a little bit leary of comments, for two reasons, essentially stylistic.

First: comments used to be a sign of good code. In recent years, though, they've been severely challenged; lots of people now think that code should be clear enough that comments are seldom needed.

Second: in my experience, Tinderbox actions work best when they are simple. Complicated actions are often a sign that you'd be better off moving  a conditional rule to an agent, or splitting a complex agent into several cooperating agents.

There's also a syntactical question.  The "//" form of comment only works with code notes, since only code notes have an end-of-line.  Is that a good idea?  Or do we also need /* ... */ style comments?  If the latter, this introduces the specter of unterminated comments.

I'm not religious about any of this; but I think it's worth thinking through.

Title: Re: Commenting Code
Post by Ted Goranson on Apr 23rd, 2015, 12:49pm

I’m with you when it comes to actual programming.

But my case is that I find action code powerful, but riven with gotchas. The syntax is tumble bumble. I am coming back to code written years ago. I do have very good notes in a KA about what I was trying to do, overall. But KAs are not as easy to browse as Text. And I find it sometimes easier to start over.

It could be that KA notes would do. But many of my notes apply to specific lines.

Why in the world did I use flummox(not) instead of flum.mox.boo?

What was the tradeoff I made when calling a named color instead of a hex value? Why interpose a guard value? Is that KA peculiar to this action or did I allow it to be changed elsewhere? Does this depend on a macro set elsewhere?

I know you need to resist folks thinking action code is programming or even scripting. But Mark, it is hard, hard, hard to keep track of all the peculiarities.

Comment notes could help.

Title: Re: Commenting Code
Post by Barbara Snyder on Apr 27th, 2015, 7:17pm

FWIW, I use shift-return to put EOL in any rule, query etc so I can read it better. For commenting purposes, could these be made into "real" EOL? (I understand if the answer is no for technical reasons.)

As for the specter of unterminated /* ... */ comments, that's user error that we each just have to take responsibility for. I have always used macros to type the opening and closing markers at the same time and then position my cursor between them.

At a minimum, if we could have comments (either or both styles) in code notes only, that would be a great start. I have taken to duplicating my code notes and writing comments in the text of the copy. I just have to remember to delete or disable the rule that sends the text as a rule to my prototype! :P

-- Barbara

Title: Re: Commenting Code
Post by Mark Anderson on Apr 28th, 2015, 4:48am

To enter a line break in a code input box (e.g. rule inspector), use Opt+Return. In actual action code, a line break is specified as \n. If comments were discrete expressions beginning ending with a line break and comment marker(s). For example:

\n//… comment here …;\n
or
\n/*… comment here …*/;\n

There are still problems, e.g. in the user has single/double quote characters in the comment string. Also if a comment is a non-action expression, it precludes  rich commenting as in a comment between sections of a long expression.

For code notes, I like Ted's approach of corralling them in one container with an user attribute for explanatory comment such as the note(s) being effect - most often the rule of a prototype. But another alternate or complimentary housekeeping method might be to add a 'code' link type to your doc and drag a code link-type link from the code note to the note(s) is affects.  That way a complex doc can be queried and 'lost' code notes tracked down.

Also remember to turn off Edit -> Substitutions -> Smart Dashes. As at v6.2.1 this is on by default for all notes except export templates made using the HTML Template prototype. Oddly, smart dash/quote substitution menu settings in prototypes aren't inherited. The substitution menu setting doesn't alter the note's $SmartQuotes either.

Title: Re: Commenting Code
Post by Ted Goranson on Apr 28th, 2015, 9:20am

Sorry to waffle, but the more I think about this the lower I think the priority should be. I can surely live with the current approach of using a KA for comments.

I wonder? Suppose I used a code note and had links from text in that note. I think the links would not inhibit export as action code.

— Ted

Title: Re: Commenting Code
Post by Mark Anderson on Apr 28th, 2015, 10:20am

From a quick test - v6.2.1 - that works. I made a code note with the $Text: $Color="bright blue". I then linked the '$Color" to note the code would affect using a new link type of 'code'. The note's rule' wrote its $Text as the rule of the target note and $Color changed as expected.

The only downside is that the target note's outline icon now shows an inbound link. Of course on a Map, the link type can be set to not be visible.  also if doing link-based code checks, you'd need to filter out the 'code' as there's no method to make it a non-counted type like prototype links. So, it works but YMMV and of course others using you file might have a bit of head scratching if the trick wasn't first explained to them.

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.