multiline comment: triple '-' format

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

multiline comment: triple '-' format

spir
Hello,

I would like to be able to write multiline comments using a nicer format such as:

  --- starting
  following
  ending ---

  ---
  starting
  following
  ending
  ---

for the following reasons:
1. Nicer to type.
2. Much less visual noise.
3. I just had a bug because ']]' was part of a comment.
This could be either an alternative or a replacement for the present pattern. At first sight, I cannot see any parsing problem. Also, "---" can hardly happen by chance inside a string or comment.

(About the bug issue, I read somewhere that a solution may be to require ending multiline comments with "--]]" instead of "]]" alone, and I fully agree (I do it now). But it makes points 1 & 2 even worse.)


Denis
________________________________

la vita e estrany

http://spir.wikidot.com/
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Enrico Colombini
spir wrote:

> I would like to be able to write multiline comments using a nicer format such as:
>
>   --- starting
>   following
>   ending ---
>
>   ---
>   starting
>   following
>   ending
>   ---

I think that would break all my Lua code and I suspect I'm not alone :-)
(I use lines of '-' as visual separators)

   Enrico
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

David Jones-4
In reply to this post by spir
2009/12/11 spir <[hidden email]>:
> I would like to be able to write multiline comments using a nicer format such as:
>
>  --- starting
>  following
>  ending ---

Trivial changes to Lua syntax are very popular suggestions from people
new to Lua ("!=" is very popular too, also the use of && and || from
C, and of course, see endless lambda discussions).

Happily these suggestions never seem to result in the language changing.

I am amused to note that your comment syntax means that a '---' at the
beginning of the file would make all code comments, and all comments
code.

drj
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

spir
In reply to this post by Enrico Colombini
Enrico Colombini <[hidden email]> dixit:

> spir wrote:
> > I would like to be able to write multiline comments using a nicer format such as:
> >
> >   --- starting
> >   following
> >   ending ---
> >
> >   ---
> >   starting
> >   following
> >   ending
> >   ---
>
> I think that would break all my Lua code and I suspect I'm not alone :-)
> (I use lines of '-' as visual separators)
>
>    Enrico
>

Awa! Didn't think at that...

Denis
________________________________

la vita e estrany

http://spir.wikidot.com/
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Javier Guerra Giraldez
In reply to this post by spir
On Fri, Dec 11, 2009 at 12:53 PM, spir <[hidden email]> wrote:
> 2. Much less visual noise.

long comments (especially the endings) should be BIG and NOISY.  that
way it's hard to miss where it finishes when quickly browsing through
the code.  --- is too hard to tell appart from --, especially when
scrolling quickly.

and, of course, your editor should display differently the commented
code, so you wouldn't have your (3) problem.

--
Javier
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

spir
In reply to this post by David Jones-4
David Jones <[hidden email]> dixit:

> 2009/12/11 spir <[hidden email]>:
> > I would like to be able to write multiline comments using a nicer format such as:
> >
> >  --- starting
> >  following
> >  ending ---
>
> Trivial changes to Lua syntax are very popular suggestions from people
> new to Lua ("!=" is very popular too, also the use of && and || from
> C, and of course, see endless lambda discussions).
>
> Happily these suggestions never seem to result in the language changing.
>
> I am amused to note that your comment syntax means that a '---' at the
> beginning of the file would make all code comments, and all comments
> code.
>
> drj
>


Pleased to read you're amused. Why you would enjoy starting a code file with an unmatched "---"? Note that your comment applies to various syntactic tokens in numerous languages. (Python coders sleep well with """ and '''.) Present Lua multiline marks introduce another issue. (Both beeing solved by proper syntax highlighting, btw.)

Side note: I _greatly_ dislike the tone of your reply. There was nothing offensive in my post, afaik, or was there? Maybe I mistake it because of non mastering english language; in which case: excuse me.


Denis
________________________________

la vita e estrany

http://spir.wikidot.com/
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Matthew Wild
2009/12/11 spir <[hidden email]>:

> David Jones <[hidden email]> dixit:
>
>> 2009/12/11 spir <[hidden email]>:
>> > I would like to be able to write multiline comments using a nicer format such as:
>> >
>> >  --- starting
>> >  following
>> >  ending ---
>>
>> Trivial changes to Lua syntax are very popular suggestions from people
>> new to Lua ("!=" is very popular too, also the use of && and || from
>> C, and of course, see endless lambda discussions).
>>
>> Happily these suggestions never seem to result in the language changing.
>>
>> I am amused to note that your comment syntax means that a '---' at the
>> beginning of the file would make all code comments, and all comments
>> code.
>>
>> drj
>>
>
>
> Pleased to read you're amused. Why you would enjoy starting a code file with an unmatched "---"? Note that your comment applies to various syntactic tokens in numerous languages. (Python coders sleep well with """ and '''.) Present Lua multiline marks introduce another issue. (Both beeing solved by proper syntax highlighting, btw.)
>

I think you misinterpreted the tone of David's email. I was also
amused at this when he pointed it out. Things like that are
interesting, it would allow one to embed 2 programs into one file, and
change which one executes by adding/removing a - at the top of the
file.

On the other hand no, I'm not sure idea is practical... I also use
multiple - as separators.

Matthew

PS. Please don't misinterpret the tone of /my/ email :) Assume all
emails are good-natured and you'll do fine, that's what I do.
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Petite Abeille
In reply to this post by spir

On Dec 11, 2009, at 6:53 PM, spir wrote:

>  ---
>  starting
>  following
>  ending
>  ---

-- starting
-- following
-- ending

clear, consistent and unambiguous :)



Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

David Jones-2
In reply to this post by spir
2009/12/11 spir <[hidden email]>:

> David Jones <[hidden email]> dixit:
>
>> I am amused to note that your comment syntax means that a '---' at the
>> beginning of the file would make all code comments, and all comments
>> code.
>>
>> drj
>>
>
>
> Pleased to read you're amused. Why you would enjoy starting a code file with an unmatched "---"? Note that your comment applies to various syntactic tokens in numerous languages. (Python coders sleep well with """ and '''.) Present Lua multiline marks introduce another issue. (Both beeing solved by proper syntax highlighting, btw.)

Ooh. You're right about """ in Python, I hadn't spotted that.  You can
flip code and strings around the same way... Hmm. :)

>
> Side note: I _greatly_ dislike the tone of your reply. There was nothing offensive in my post, afaik, or was there? Maybe I mistake it because of non mastering english language; in which case: excuse me.

Well, I didn't intend to offend, but it's just possible that some of
my tiredness at reading so many syntax discussions came across.  To be
perfectly honest, discussing syntax is fun (I like writing lexers and
parsers), and it's easy.  Every programmer knows a bit of syntax, it's
what they have to type every day.

But in the end I've seen too many languages to think that syntax is
_very_ important.  It is important to pay some attention to it, but
Lua's syntax is fine.  It's not so horrible that it would interfere
with programming on a day to day basis (I program in Python a lot, and
after years and years I _still_ think that its whitespace is a stupid
stupid feature, but I just live it.  I cope).  Yes, when I return to
Lua after a break, I do have to pause to remember that not equals is
~=, and a bunch of other things, but it's all fine.

drj
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Matthew M. Burke
In reply to this post by spir
spir wrote:
> for the following reasons:
> 1. Nicer to type.
> 2. Much less visual noise.
> 3. I just had a bug because ']]' was part of a comment.
> This could be either an alternative or a replacement for the present pattern. At first sight, I cannot see any parsing problem. Also, "---" can hardly happen by chance inside a string or comment.
>  


It seems to me that 1 and 2 are just personal preference (which is not
to say you're not entitled to your opinion...).

As for the last comment, both I and many people I know frequently use
"---" inside strings and comments.  Many writers (and programmers) use
it to offset a subordinate---or parenthetical---clause from the rest of
the sentence.


Finally, "---" as a long comment delimiter probably would interfere with
LuaDoc---which probably doesn't get used as much as it should :)

Matt

Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

spir
"Matthew M. Burke" <[hidden email]> dixit:

> Many writers (and programmers) use
> it to offset a subordinate---or parenthetical---clause from the rest of
> the sentence.

I have always seen one '-' or two '--' (use 2 myself). The reason why I thought '---' could hardly happen by chance.

> Finally, "---" as a long comment delimiter probably would interfere with
> LuaDoc---which probably doesn't get used as much as it should :)

Yes. And precisely I thought at that :-) (Just like python docstrings.) Instead of "interfering", in my mind it would be intentional.
Anyway, seems that this proposal has no chance. Also, the objection about a whole line of dashes as visual separator is really valid.

Denis
________________________________

la vita e estrany

http://spir.wikidot.com/
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Tobias Kieslich
In reply to this post by spir
Hi,

I have an idea where you are coming from and nice code is always good
but especially the the multiline stuff in Lua is nice because even
though it is a tad noisier it actually allows for nested comments:

--[=[
        chunk of code
        --[[
                Longish comment ...
        --]]
        code
--]=]

which makes it really easy to take out code segments for testing. That
is a powerful feature I don't wanna miss.

        -T
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

spir
Tobias Kieslich <[hidden email]> dixit:

> Hi,
>
> I have an idea where you are coming from and nice code is always good
> but especially the the multiline stuff in Lua is nice because even
> though it is a tad noisier it actually allows for nested comments:
>
> --[=[
> chunk of code
> --[[
> Longish comment ...
> --]]
> code
> --]=]
>
> which makes it really easy to take out code segments for testing. That
> is a powerful feature I don't wanna miss.
>
> -T
>

Thanks for the explaination. Precisely I wondered about nested comments' use case. (About the purpose of such a complicated syntax for comments and string.) What about nested (multiline) strings?

Denis

PS: I don't wish lua be more whatever-language-like. (Except I would be pleased if mainline languages had adopted concatenative postfix syntax instead, as it brings imo relevant advantages.) But I find sensible to watch what others do well, when it can fit the rest of our language.
________________________________

la vita e estrany

http://spir.wikidot.com/
Reply | Threaded
Open this post in threaded view
|

Re: multiline comment: triple '-' format

Philippe Lhoste
On 12/12/2009 11:18, spir wrote:
> Tobias Kieslich <[hidden email]> dixit:
>> --[=[ --]=]

I wondered when somebody would point out at that...

> Thanks for the explaination. Precisely I wondered about nested
> comments' use case. (About the purpose of such a complicated syntax
> for comments and string.) What about nested (multiline) strings?

Search "Literal strings" in the manual, it explains this, and the fact
you can nest at several levels. Same (similar) syntax for multiline
comments and strings.
BTW, I don't find this syntax "complicated". You have to do something a
bit convoluted so the end of comment/string isn't meet usually in the
text they surround. In the past, Lua has only [[ and ]] and people were
meeting the a[b[c]] problem, so they added the [=*[ ]=*] syntax.

--
Philippe Lhoste
--  (near) Paris -- France
--  http://Phi.Lho.free.fr
--  --  --  --  --  --  --  --  --  --  --  --  --  --