Deciding on an Alternative Comment Syntax


#21

Four out out five of these assertions are absolutely wrong and off topic.

Questioning and thinking about everything in Rebol is relevant and fair game in this project including aesthetics. Some people value aesthetics more than others, but if chosen well for a language they provide benefits to everyone.

I do not have strong opinions on comments expecting them to be chosen according to the needs of the language, but I don’t think they’re that great for comments. Yes the lexical space is important, maybe why Carl chose semicolon, because he didn’t think he’d use it anywhere else.


#22

Which one was correct?

I’m still suggesting that \ could be used for line commenting. It’s not used in Rebol otherwise, and it’s an invalid word currently.

It’s solid, and not flimsy like ; and doesn’t need double typing such as -- and doesn’t remove from the lexical space. Why doesn’t anyone like it? Because they’re not used to it; it’s a forth covention so Carl would be quite used to it since he wrote his own forth.


#23
some (code [that looks]) kind of Englishy \ a Rebol comment

I do agree it stands out more boldly as a single character than semicolon, and it’s true it doesn’t have any other use today (outside of appearance in string literals).

However:

  • It is truly unfamiliar, the least common of choices we’ve spoken of (; is very popular among other languages by comparison). Regardless of any merits it may have, that can wind up being a liability when it comes to first impressions…when a more familiar choice like // wouldn’t cause anyone to blink.

  • No matter what single character you use for a comment, just having a single unit of width may still be too thin and easily overlooked…considering that it completely shifts the semantics to “computer-not-reading-it-anymore”.

  • The common usage of \ for escapes in several mediums means trying to paste code strings that use them can be a problem. I can’t seem to reproduce the exact problems in SO chat I remember having when we were discussing it as expression barrier (e.g. [a \ b \ c]) so maybe they’ve changed it there. But it has problems other places, you couldn’t put it in a C string literal without turning it into \\ for instance.

Note: **\\** in MarkDown comes out as a single slash here on Discourse, you have to put backticks in it, then what I actually had to write to get that was:

`**\\**`

And I don’t know how to get MarkDown to show that inline with my sentences using asterisks and backticks. I could only get it by putting it indented on its own line as a code block, as above.

  • @MarkEye (or @Mark-hi, or whoever he is these days, could we consolidate those accounts?) raised a point that there is a value in the design to reserve a character that you don’t use in the language at all. That gives templating systems a “meta” escape, so if you think there might ever be a reason to slip some backchannel information into a Rebol script when being processed by non-Rebol tools it could come in handy there. One could make ^\ an escaping for backslash in strings to further facilitate such applications (currently it is an escaping for ascii 28, or “file separator”, which is not very useful by comparison)

e.g.:

Rebol [
    Title: {Script munged by non-Rebol-LOADing preprocessor}
    Purpose: {
        The idea here is that you've got a dumb tool that doesn't
        know anything about parsing Rebol, but is able to safely
        mess around with a script written in Rebol using a basic
        substitution mechanism.
   }
 ]

// Preprocessor can use a simple check to ignore ^\
print {
    Escaped ^\ could be another way of having backslash in
    strings, which scripts geared toward having this kind
    of substitution done on them would elect to use to bypass
    the substitution and get a literal backslash.  However
    scripts not intended to be used in this way would just use
    a plain backslash as today.
 }

data: read %"/var/www/\$server.name\"
for-each x data [
    print [\inject $php.or.whatever %<gibberish>%\ x]
]

When you combine these motivations, I think backslash may serve a higher calling staying under the radar as it is today.

(I also prefer // for comments, myself)


Rethinking the Console Prompt: >> to ? or .\
#24

The current comment delimiter is also okay if embedded into a literal string.
Or, if necessary we could make it \space
I do find using the caret ^ annoying I came across lots of carets in some JSON which we had to escape.


#25

I’m only replying to what is probably rhetorical because I don’t want to imply any support for any of the assertions. “not an improvement” was on topic if it was defending semicolon, but maybe I misunderstood that.


#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

Rethinking the Console Prompt: >> to ? or .\
#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.


#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.


#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.


#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.