Deciding on an Alternative Comment Syntax

I wonder if we can embed in REBOL header some switches driving the parse process -- I think at: 1) comment syntax 2) escape char in string; i.e. I'd like to write

REBOL [comments: "--" escape: "\"] "this \/ is a newline, this ^ is a caret" -- and this a comment

One argument against semicolon as comment character which has not been emphasized is that it looks a lot like a colon. Imagine someone wanting to comment on what the contents of a variable later down on a page, for instance, and that looking like an assignment:

foo: {bar}
...
print foo; {bar} 

Just another problem. I still regularly tinker with the source to see how I feel, and if // is the answer.

So today I had a thought that hadn't come up, about double-bar. It has some of the nice "unbroken" properties of //. It might seem like a greater-emphasis version of the "barrier" notion of BAR!.

something: function [ ][ || start
    foo: #bar || important
    collect [ || collect
        keep #foo || foo part not #baz
        keep foo || bar part
        keep #{DECAFBAD} || requisite binary
    ] || end collect
    ||no space required
] ||end

Comparing again with double-semi:

something: function [ ][ ;; start
    foo: #bar ;; important
    collect [ ;; collect
        keep #foo ;; foo part not #baz
        keep foo ;; bar part
        keep #{DECAFBAD} ;; requisite binary
    ] ;; end collect
    ;;no space required
] ;;end

And then again with double slash:

something: function [ ][ // start
    foo: #bar // important
    collect [ // collect
        keep #foo // foo part not #baz
        keep foo // bar part
        keep #{DECAFBAD} // requisite binary
    ] // end collect
    //no space required
] //end

I think double-slash still has the edge, here. And of all the options examined, it's one from other languages that people will just accept. I still haven't done it yet, but I still think it's likely to be the best idea that's going to come along, and so it's probably what's going to happen.


I've also come to be thinking about the merits of using things like === (or, ==, once retaken) as "live" comments, even using variadic syntax and normal Rebol words:

 == STARTUP ==

 config: load %/home/duck-detector/config

 == MAIN LOOP ==

 until [...]

We've even discussed if newline flags are something that can be exploited, you might be able to omit any tail signals and just say == MAIN LOOP, like in MarkDown:

### THIS IS LEGAL MARKDOWN HEADER SYNTAX ###

### SO IS THIS

The downside of this is that your comments have runtime cost, and you're limited to Rebol syntax (which isn't that limiting, especially for writing in headlinese). The upside of this is, they have a runtime presence, you might have a debug level at which they print as they go by...or get written to a log. Or you could even ask the debugger to break there, by name.

But when you encap your script, all those comments get stripped out, and the script is compressed so does it really matter?

Well that's why I said that I was thinking about the comments that don't get stripped out, and if the "long tail" of things would suggest perhaps that learning to write your comments in Rebol syntax and == USING REBOL == would be the longer-term concept.

For me I like the semicolon. Nice and short, doesn't take much visual space, Every time I use one as a comment I think about all the semicolons I do not have to add to the source in languages where the semicolon is a line terminator and I feel a little happiness bubbling up.
I do not mind additional methods of commenting being added, although some of the ones discussed here are unpleasant to look at imntho.

2 Likes

So the time has finally come. We've decided to enfix MOD and make it a synonym for MODULO, so you can use that where // was before. Hence instead of:

value1 // value2

You now say:

value1 mod value2

Which I would say looks more coherent to programmers and mathematicians alike.

I also feel that when you look at the philosophy put forth about usage of these kinds of clumsy "barrier" looking symbols, they really don't belong as plain code constructs.

Recent experience also has spoken to how unpleasant it is to be commenting a mixture of JavaScript and Rebol. Comments are language-independent, it's just stuff you're saying. So being able to annotate the file wherever you are with the same style of comment is ideal. You get an idea of how ugly ;; is by looking at the replpad demo at the moment:

So I want it known to people that this was by no means some kind of impulsive copy of C or C++ into Rebol. This was a very long, and extremely deliberated change. It has a basis in fact and practice, and I believe it will bear out benefits making it well worth it. Hear me now and believe me later.

And it is committed. Obviously it shouldn't be used in files that need to be LOAD-compatible with older Rebols or Red, and also one doesn't have to use it if one doesn't want to. And so, let's try getting some experience with it. If people find any particular weird issues with the scanner involving multiple slashes, let me know.

Well do not use double semicolons

;   ----------------------------------------------------------------------
;  
;   File: %replpad.reb
;   Summary: "Read-Eval-Print-Loop implementation and JavaScript interop"
;   Project: "JavaScript REPLpad for Ren-C branch of Rebol 3"
;   Homepage: https://github.com/hostilefork/replpad-js/
;  
;   ----------------------------------------------------------------------
;  
;   Copyright (c) 2018 hostilefork.com
;  
;   See README.md and CREDITS.md for more information
;  
;   This program is free software: you can redistribute it and/or modify
;   it under the terms of the GNU Affero General Public License as
;   published by the Free Software Foundation, either version 3 of the
;   License, or (at your option) any later version.
;  
;   https://www.gnu.org/licenses/agpl-3.0.en.html
;  
;   This program is distributed in the hope that it will be useful,
;   ----------------------------------------------------------------------

looks fine to me.

Well do not use double semicolons

Not the point (though those are going to become slashes).

The main point is to look further in the file, where one is inside a JavaScript body of code and uses // because you cannot use semicolon, and then outside that string literal you are forced to use semicolon.

foo: js-native [...] {
    some.javascript(code); // a comment inside
}

; now we are outside but have to change comment styles
bar: function [...] [
    some rebol code ;; and it looks bad and is frustrating to switch
]

There is a definite blindness to those who do not realize the unfitness of semicolon for this purpose. I think you'll have to take the opinion of the person who is a graphic designer, over the force of one's own habit.

Comments ARE language dependent.
Languages NEED every chance they get to let you know which language you are staring at and/or typing in.
I really don't like repurposing a perfectly good REBOL word as comment syntax.

One thing that helps REBOL be readable and usable even though it combines infix and prefix operations is to make the words of the former be symbol-heavy if not solely symbolic (think + - *) and have the latter be (prefereably correct English) alphabetic-heavy if not solely alphabetic (think head reverse sort copy data).
Even adding arrow-words to the language was welcome as a way to increase the space available for those symbolic operations that make sense to be infix.
Having words (like MOD) be infix is wrong. Even AND and OR are inherently wrong, but they can be put up with, just like ? can be put up with as being prefix. A limited number of special cases is bearable. But there needs to be push back on going against this readability idea in general, and ESPECIALLY if it's being done just to forward a single-person agenda of allowing // for comments.
I'm not even going to mention that this change is also extremely horrible because it destroys all slashes words, not just //.

1 Like

It is pleasing to see you have other code in a js-native versus a true function containing Rebol code.
Also writing less JS code is better (almost state: in all cases).
Rebol just is not C code and its comment is thus different. The semicolon is good as is, it finally has got a good place as a comment signal.

1 Like

I'm the one writing the codebase which mixes JS and Rebol in the same file. And I can tell you that no, it is not a pleasing aspect to have the two styles--and I will not be the only one who feels this way, at such time as I am not the only one writing such code.

Until then I am the sole authority on the matter.

There is nothing "perfectly good" about // being a WORD!. Making / a zero-element PATH! combined with not having / in words solves several major problems in the language. I'm not going to repeat the discussion... again.

So now that I've had the option of // for a while, and getting to try it, I'm finding I'm not as happy with it as I thought I would be.

Don't get me wrong--I still hate semicolon. But in light of the recent change to make backslashes a generic escaping mechanism, using slashes for comments is making the code look... too "slashy".

Basically, as frustrating as it is to say it, I think backslashes for escaping has reopened this issue.

UPDATE: Maybe not, backslash may be the wrong choice, perhaps % is better. So possibly disregard this post, stay tuned.

In examples I look at, this keeps coming up as being a clear winner. Easy to type, you don't take your hands off the keyboard. It's clean.

After endorsing -- initially, why did I back off?

At first I felt it had to be the winning thought. But then @draegtun expressed skepticism about the fact that - was a legal word character, and then some experiences noticing -- occurs on command lines scared me off.

But Rebol will walk on the edge of uncomfortable decisions, if it means a better overall experience. a / b and a/ b and a /b and a/b are all different. That's how things roll, even if it makes people squirm at first. It's the reality of experiencing the code in real life that shows why you'd make these odd choices. So maybe --foo is a WORD! and -- foo is a comment, and that's not crazy. Or maybe any word starting with more than one dash is illegal, I don't know yet...I'm just putting this back on the table.

One interesting thing that backslash opens up is that \-- would be an escaped WORD!. That feels more solid and "hearty" than '--, you won't mistakenly think that's a comment.

MARKETING PITCH: Three Styles?

People have varying tastes in commenting styles, and it's something they are frequently passionate about. The lexically rich space of Rebol makes it tough to prescribe any one form...depending on what you're writing, certain characters will stand out more or less. So it allows for any of three popular choices from other languages:


Lisp/Assembly style: This is Rebol's classic style, supported by all versions, as well as Red.

   your <code> "here" ; a semicolon comments to end of line

It's concise, takes only one character to type, and is one of the easiest keys to press on most keyboards. Semicolons aren't used anywhere else in the language (besides inside string literals), so they invoke commenting behavior at any position they are used...with or with;out spacing.

ADA/Haskell style: This is new to [Beta/One].

   your <code> "here" -- two dashes comment to end of line

This is a comfortable and clean notation. It addresses the frequent practice of wanting to make the slight and easy-to-miss nature of semicolon by using ;-- which was a three character combination with a somewhat "messy" look. However, hyphens are legal in identifiers in Rebol, so the convention of needing a space before the comment is enforced. (other rules...?)

C++/JavaScript style: This is new to [Beta/One].

   your <code> "here" // double slashes comment to end of line

Rebol uses the slash character much like other languages might use a "dot", in PATH!. Hence it makes a poor character to use in names of WORD!s. That frees up // for its semi-ubiquitous use in commenting. It has a visual cleanliness which ;; does not. Double slashes appear in URL! literals, hence it is necessary to have a space before them to get commenting behavior.


Which one should you use? For maximum compatibility in the Rebol space, choose semicolon. But if that's not a concern, use the one you're most comfortable with.

Note also that dialects can look very different from code written to run in the evaluator, so one size may not fit all... which style you use could be dialect-specific (and even help visually cue which dialect you are in!)

Sadly, this would mean DUMP would get pushed back to ??. But, worse things have happened. I can live with it if it means comments will be better.

I don't have a firm feeling, but I just want to put the question back on the table, now that we've got all these backslashes showing up.

I'm on favour of Ada style because the French typography use the cadratin dash, equal with three dash long, for embedded comments in a sentence. It's used also for a comment at the end of a sentence. Really like in code. Sample :

The weather is sunny --- gold day.

The weather is sunny --- good day for walking --- as we expected the last week.

For example Oberon use # as an operator for inequality:

IF var1 # 5 THEN
    doSomething();
END

I dunno...it's actually kind of tempting to allow that one to be a comment too. Why not do a clean sweep and have all four popular options? It would be in the spirit of the most freeform programming language ever invented...

What I point out is that whether a character is going to blend in too much and look like code or not depends on what you're writing. Some dialects would fit well with # as a comment character, if they don't use ISSUE!s, but use a lot of PATH!s and backslashes. Others use a lot of ISSUE!s and no slashes. Etc.

The one thing semicolon has going for it here here is simply not being used for much... kind of because it's a lousy character that's too close to colon. But being unliked means it probably shouldn't have a monopoly on one of the most important jobs!

I don't see the point of providing 4 comment styles (outside of a test period) because a comment do nothing from the point of view of the computer. Why more ways of doing nothing?

Choosing a comment style that interfers less with code is yet better.

A more powerfull system could behave like a literate program , embeding code in documentation and exploring it, but the current way of doing it had not proved to be really effective because the flow of documentation and code are different but mixed in the same file.

An active documentation format executing self exploratory external rebol code with a a dialect for loose coupling could be better.

I agree with any kind of commenting which takes into account structured or semi-structured metadata to improve documentation and literate programming. A big thumbs up for that thinking.
I want to be able to query & inspect my code/scripts/libraries for different purposes; for resuability, to spot & refactor outdated code patterns (e.g, for interpreter updates), etc. I suppose at some point this resembles a version control system, although with a truly literate programming approach, it becomes more like a content management system.

Fair enough...well I think all the angles have been seen at this point, so time to close the issue.