Deciding on an Alternative Comment Syntax

Development Naming
26

I agree, it's tempting, because it is so close, but it does feel a little messy / wishy-washy.

>>
    Do you like this? Maybe these characters are already used?
    This has typically been used for bit shifting in other languages.

    It does draw your eye toward the comment, like it is pointing at 
    something you should pay attention to. There is a nice symmetry 
    if you were to use << for the closing of multi-line comments too.
<<

something: function [ ] [
    >> foo has something important to say,
    >> see how this stands out from the actual code
    foo: #bar

    >> collect the values
    collect [
        keep #foo         >> foo part not #bar
        keep foo          >> #bar part
        keep #{DECAFBAD}  >> requisite binary
    ] >> end collect
] >> end
27

I have the impression from some long-forgotten source that Carl picked the semicolon for comments so he wouldn't have to remove his fingers from the keyboard. I myself do like that feature. However, I also would not mind if there were some comment character that was the same for all/most languages. That way, a person could make up some little embedded syntax for some as yet-undefined reason and embed it in code using the comment character which would be the same for all languages. Other than that I get along very well with the semicolon for comments.

2 Likes
28

You mean http://www.rebol.net/cgi-bin/r3blog.r?view=0017

29

YES!. You have quite the memory.

30

Not really, I just used a better google search term!

31

Don't despair too much, in the sense that by retaking -- from decrement, it will be freed up for various styles of documentation or interjection. The other day I thought it would be nice to document spans of tests with their issue numbers, e.g.:

-- #1020 --
[x > 1]
[x < 2]

And as proposed in the comment usages, it looks like an okay separator even without being symmetrical:

-- #1020
[x > 1]
[x < 2]

Since test is a dialect it could do that already. But I think that it might become interesting when it's freed up in DO as well, for such custom purposes. You'll have to use strings or otherwise to get arbitrary text, but I bet the applications will wind up being more interesting than for mundane math.

As it happens, I actually do kinda like how that looks, and for some of the same reason I like //. Looks like painted stripes on a raceway wall or such.

But... as I discussed in some of the out-of-band-console thinking, we need to be wise about how a good asymmetric pairing like that is used in the language. I'd call Rebol2/R3-Alpha's/Red's borrowing of bit-shifting from C an "unwise application", considering the domains Rebol is best suited for.

Many options have now been considered, looked at, framed and reframed... to the point I think there are only two choices:

  1. Leave it alone: accept ; for better or worse, 'till death do us part (though I have a feeling ; is going to outlive us).

  2. Choose // as an alternate notation for comments.

We've never actually gone as far as to try option 2, to see if there's some great unhappiness it causes or fatal flaw. It will clearly have the flaw of not being backward-compatible, but we have quite a number of syntax changes (allowing things like -> or >>= as operators, for instance). So backwards-LOAD-compatibility is not something that's going to be happening anyway, unless you constrain your usage to older patterns. This would still be an option as no alternate purpose for ; is being proposed.

I think it's time to try //, work out the details, and see how it feels.

The way has been paved by the ME commit. (which was followed soon after with a MY commit, once I figured out a trick to do it)

So after a bit of a settling period, we'll try it.

1 Like
32

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

33

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.

34

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

35

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.

36

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
37

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.

38

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.

39

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.

40

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.

41

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
42

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
43

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.

44

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.

45

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.