I’ve updated my note on action code commenting to reflect this hard-to-guess (especially for non-coders) behaviour for unpaired quotes and re line-wrap and the fact the code parser and code colouring are separate processes with possible different implications.
In the following example ignore the code colouring added by the forum software…
BAD. Unpaired straight quote:
// don't do this.
GOOD. Uses curly quote for apostrophe:
// don’t do this.
GOOD. Avoid speech-style contraction:
// do not do this.
BAD. Unpaired double quote in wrapped comment text.
// Here is "Some
// wrapped quote text". Etc...
GOOD. Wrapped partial quote is fully quote-enclosed:
// Here is "Some..."
// "...wrapped quote text". Etc...
GOOD. Uses curly double quotes for quoted text:
// Here is “Some
// wrapped quote text”. Etc...
Also, action code comments do not have an explicit multi-line method. I have had odd effects if I just let the comment soft-line wrap. For this reason, and pending any changes to comment function, I think it best to hard-break a long comment into a series of single like comments. So, instead of this:
I would do the comment like so:
This makes it far less ambiguous for Tinderbox’s action code parser—which is process discrete from the regex doing the code colouring. the code colouring should be seen as a guide to typos buy won’t warn of things like lines of code lacking a ‘;’ terminator or lines wrapping owing to the RTF-style ruler.
Lest someone point it out, yes, I am suggesting judicious use of curly quotes in code comments as opposed to the actionable code itself as a means to avoid confusing the code parser. For more complex code use like functions—especially if to be shared with others—good and clear comments are a good thing (plus we all forget our own code’s meaning after a few months)
