Deciding on an Alternative 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 //.


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


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


I love arbitrary escaping, but backslash may not be The One
#46

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.

#47

For example Oberon use # as an operator for inequality:

IF var1 # 5 THEN
    doSomething();
END

#48

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!


#49

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.


The Beta/One Comment Concession
#50

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.


#51

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