Block or Multiline Comment

[hopscc]

I've been fiddling with some Code refactoring in Cobra and it turned out convenient to be able to comment out
but otherwise leave unchanged blocks of cobra code.

Rather than relying on whatever local editor support there may be for that I added some Cobra support for it by recognising and ignoring anything between a
couple of block markers.

Implemented syntax uses a triplet of chars only at the start of a line to delineate the start and end of the commented out block..
Anything else on these lines is ignored

Code: Select all

##{
    .someCode( not compiled)
   whatever is in here is swallowed up and ignored
   up to the end block marker below
##}


Is this likely to be generally useful or total anti-cobra (cobra bite antidote ??)
i.e is it worthwhile adding some unit tests and submitting a patch?

[Charles]

As you seemed to suspect at the end of your message, it doesn't quite feel right. I've been using on old Python trick to disable statements. I put an "if false" and indent the statements that follow. Although that doesn't work for declarations.

Maybe we can revisit this idea when we decide on a "precompiler" syntax.

[hopscc]

Wasnt that it didnt feel right - I thought I'd seen somewhere that you'd said you'd not provided any block comment/comment out capability but couldnt remember where or what the reasoning was...

A workaround that requires 2 passes over the blocked code (reindent - once on commenting and once on uncommenting) does seem a little ..... suboptimal ... though .

Not wedded to the syntax - ''precompiler' syntax is fine - I'll open a reminder ticket for it

[hopscc]

For ref heres a code patch for the change

[hopscc]

and heres a test file for it

[Charles]

I don't like the syntax for various reasons:

-- Aesthetically. It looks like a Cobra dictionary or C code block embedded in comments or something...

-- ##{ is also a valid single line comment which could be confusing

-- It might be difficult to get editors to recognize this given that # is also as single line comment.

One thing that I occasionally miss in Python is the ability to create inline comments which I sometimes want to use for arguments:

Code: Select all

foo(x, y /*blah*/, z)

Should we support C-style /* ... */ comments? They are well known and editors will certainly support them. They can be used for both multiline and inline comments.

-Chuck

[hopscc]

Aesthetics: - yes it could conceivable be mistaken for some sort of commented Dictionary and its reminiscent of any algol based language block structure ( C, Java, C#, ...)
OTOH if the line is thought of as cobra it is commented ( leading # as next point) and the Cobra language is not syntax oriented from anything algol like anyway

Leading # as line comment
True but thats the idea - # is a comment #<something> is a comment block leadin (line comment on steroids).
Compare with augmentations of C language for doc or pretty display or formatting purposes
( /* vs /** and /**********************************************...) - its still a comment but more-than a single line comment.

Editor recognition: Not been a problem to date. Most editors support both single line and multiline commenting as a hierarchy with multiline being 'higher' than single - at least thats been the case with the (small) sample I've tried configuring with this...

I chose a # leading trigraph reasonably deliberately:
- Leading # to have some similarity or closeness to the # line comment - on an eyeball code scan then anything with a leading # is instantly and solely identified as some comment form.
- The trailing char { as indicative of this being a block enclosure (therefore '}' as closing the block. (alternatives would be () [], perhaps // or \\ or /\,...)
the other advantage of these chars is that most editors have some existing for support balanced bracket matching to jump to end/start of these.
- the middle # ( or leading double #) to indicate some sort of extended comment ( # is comment, ## is comment with extra sauce) and also to make the token less likely to collide
with some line commented out code ( like a dictionary literal).


Yeah it might be convenient to have floating block comments from anywhere in a line - I havent had a need for it yet strong enough make an itch worth scratching but..
Theres also something of a complexity issue with a floating block comment that starts/ends in the middle of a line ( pathologically) - what does that do with (commented and uncommented) indentation?

For your example in a mostly line oriented language I'd just insert a comment for the remainder of the line and insert the replacement

Code: Select all

foo(x, y ,z ) #  y blah, z)   


OR just

Code: Select all

foo(x, y, z)  # y blah


Just for avoiding explaining what happens to indentation across multiple block commented lines when the block comment initiator and terminator are embedded in the middle of lines
and for cobra syntax being mostly line oriented I'd keep the blocking comments as also commenting the remainder of the lines they occur on
(even to the extent of forcing them to be available only at the start of lines...)
e.g. Is the indentation syntax on this valid ?

Code: Select all

    /* foo(x)
    blah(y)
    z(x)      */  fooBlahZ(x,y)


(No) - 4spaces before initiator, 1 after - how easy is it to tell
removing the space before fooBlahZ merges the active code into the comment (visually), adding more spaces screws the indentation level.........


Is /* ..*/ cobra like ?
Cobras not (strongly) C/Java/C# syntax flavoured elsewhere so I'd submit that it is not.

# is the comment indicator already - perhaps /# ..... #/ would be acceptably disagreeable to all ??

[hopscc]

To clarify the above ramblings:
We really Do need non intrusive multi line comment blocks

Dont really care what the syntax is exactly - not bound irrevocably to

Code: Select all

##{
...
##}


though think it is convenient and evocative.

think it should use # somewhere as binding/similarity to # leadin for a single line comment
For multiline commented blocks(at least) for simplicity think it should be remaining line contents inclusive
and
dont like /*...*/ very much for cobra.

[Charles]

Random thoughts:

-- Not having a block comment is still an option. Python gets along without one, almost surely because various editors support commenting and uncommenting selected lines. UltraEdit and Visual Studio both have this. What about emacs and vim?

-- Re: "Cobra...not...algol like", while that's true, curlies are used for dictionaries so it still looks like something whether you're new to Cobra (and familiar with C) or not.

-- The point about the comment ending in the middle of a line is a good one. Perhaps the solution could be to make it illegal to do so.

-- Your /# ... #/ proposal looks really neat! But I'm worried it could be ambiguous. At some point, Cobra will allow line continuations based on being inside parens (this comes straight from Python). Then /# could be interpreted as "division", "single-line" comment instead of "start multi-line comment".

[hopscc]

Sure most programmers editors have some way of doing this or can be programmed up to do so - other editors dont (wordpad notepad)
The same argument can be used for not supporting a number of things in a language - e.g. for/while looping ( if the language has if and goto) - I dont find it very convincing
( GNU emacs supports it - or can be augmented to do so .. ditto vim (macro). microEmacs doesnt out of the box but can be made to do so - need add a macro ( I havent). )

Python does manage without one and it too is a gigantic pain if you're doing widespread blocks of code mods- hand refactoring etc.... I guess you're not expected to do much
of that...
Interesting point that on some reflection - most of what are characterised as (system implementation) languages do support block comments ( algol, c c++ Java c#) and are not line oriented
most scripting languages (shell, python, tcl ) dont - but are line oriented .... which I wonder is cause and effect....

...curlies in dictionaries... - yeah what it looks like is a curly in a comment (:-) -..... so we dont use curlies

comment ending in the middle -(disallow) that was most of the note I had written about this - make it comment the remainder of the line for both the comment block initiator and terminator.

I dont see the ambiguity - the tokeniser will recognise and ignore the /# tokens up to the ending #/ passing the discovered tokens on up or not regardless of paren contin or not
- unless something stupidly pathological is done like splitting the /# with a nl in the middle in an implicit continuation

regarding "Cobra will allow line continuations based on being inside parens "
I was going to ask about that. The point cobra gets that may be closer than you expected.
I was part way through working out some additions and changes for supporting that in method calls and definitions (at least) before I switched to updating the patches
I'll probably start a discussion item on this if someone else doesnt beat me too it