The Beta/One Comment Concession

Development Internals
1

Note: People should bear in mind there was never a question that semicolon was going to stay a comment character. There was only a question of if another sequence (or sequences) would be permitted. (!)

Also, bear in mind that the alternative syntax for comments discussion started in August 2017. Hence it predated the creation of "invisibles" by about 4 months. Invisibles have offered a much higher leverage tool for machine-processable comment-like things, and to use them requires not giving up too many characters to be stripped out of source.

Ideas have been discussed and tried. But the time has run out on this decision, and status quo wins.

Semicolon will be the only scanner comment in Beta/One

Other ideas got panned for various reasons:

  • # Makes every line look like it has an #issue on it, and # is overloaded as it is (char! should probably change to & and be more compatible with HTML character entities). The use of issues and having them stand out is a more unique Rebol attraction than comments. Having lone # for a dialecting component seems nice, e.g. compose # [(1 + 2) (# 1 + 2) (1 + 2)] => [(1 + 2) 3 (1 + 2)]

  • // Tried it for a while and it didn't make it as happy as I wanted it to. Wound up desired for NewPath, as the representation of a length 3 path with blanks in it. Having blanks in paths not render affords paths like /foo (what was a refinement) and foo/ (previously did not exist).

  • -- Made up of a known legal WORD! character. Have gotten kind of attached to this as a shorthand for DUMP-to-end-of-line. Has uses in dialects, e.g. those representing command lines (it's a sequence used to indicate end of switches and beginning of parameters). Doesn't look good when doing sequential lines of comments as a block, only when commenting an existing line rightwards...which means it's not a good "one size fits all" comment form like // is for C and C++.

  • \ Only @gchiu likes it. Every time we try to talk about it, StackOverflow chat or other mediums with escaping throw a fit. My experience with trying it out for generalized quoting instead of apostrophe made me fairly convinced I hate this character in source code. I think I want to stick to @MarkI's idea that it's the one ASCII codepoint we promise not to use outside of strings, to help people making templating languages who need an escape from Rebol itself.

Recommendations

My own conclusion is that I'm going to avoid the ;-- and ;; sequences. They don't help make up for semicolon's shortcomings, they exacerbate the problem and destroy what merit it does have.

Instead I suggest sticking to single semicolons, and finding a way to space them away from the code. I personally wouldn't want to get in the business of doing alignment of semicolons to some arbitrary margin you have to maintain as you edit:

 some <code> on a #medium line       ; so I put comment here
 short line                          ; guess comment goes here, then?
 then =what= IF [I go write <some>] "Long line"    ; crap, touch all the lines now?

This kind of practice annoys me in version control due to touching lines that shouldn't have been affected. (Of course, it's text and not a graph database, so you get this with secondary changes due to indentation too.)

Instead I'd just suggest trading off something like the two spaces you might have used for a dash before, and use them for an extra space to put some distance from your code.

 some <code> on a #medium line  ; comment two spaces out
 short line  ; again, just two spaces
 then =what= IF [I go write <some>] "Long line"  ; not perfect (but nothing is)

Compare that with the alternative using another unit of character width, e.g. ;--:

 some <code> on a #medium line ;-- this seems more cluttered
 short line ;-- at least, I think it looks cluttered 
 then =what= IF [I go write <some>] "Long line" ;-- but do whatever you like

Then there's ;;:

 some <code> on a #medium line ;; this is probably even worse
 short line ;; I've tried this one for a while and pretty sure I hate it 
 then =what= IF [I go write <some>] "Long line" ;; but well, matters of taste

Embracing the single semicolon actually works pretty reasonably if you put comments on their own lines, when they line up like this their complained-about "dottedness" almost suggests a cut-along-dotted-line kind of separation:

 ; STUFF TO TALK ABOUT
 ;
 ; This isn't so bad...it's actually kind of nice

Closing This and Looking to the Future

I mentioned that we have invisibles now, and my attachment to -- for DUMP has made me reluctant to take it away from dialecting. And it's invisible, too...so very comment-like.

Perhaps its best to just repeat a mantra like what @LkpPo said:

"...a comment do[es] nothing from the point of view of the computer. Why [have] more ways of doing nothing?"

Semicolon may kind of suck as a character, but that just means it's not wanted for anything else. So it seems to have job protection/monopoly status.

The big change of taking == away from equality comparison and giving it back for marking up sections may open some doors to new and interesting forms of commenting that can actually do something (e.g. when you are in a debug mode, print out == PHASE ONE == as it passes by).

1 Like