Zig: Proposal: remove multiline comments

[andrewrk]

Status quo:

Multiline comments start with /* and end with */, and they nest. The name "multiline" is a bit misleading, because in fact, these style of comments have power that single line comments do not have, which is ability to insert in the middle of an expression:

const sum = a + /* comment */ b;

Removing multiline comments would remove this ability.

Rationale:

Modern text editors make it easy to insert some characters in front of many lines at once; commenting out a block of code by prefixing each line with // should be easy.

One of the points of contention in C is whether to use /* */ or // for comments. Only having one way to do things is one of Zig's goals.

This sidesteps the question of whether multiline comments should nest or not.

[thejoshwolfe]

Removing /* */ comments has another minor benefit, which is a step toward enabling editors to understand the middle of a large source file without scanning the entire document to find out whether or not we're in a comment or not. This goal might be a lost cause though, since string literals can still cause this exact problem.

I'm generally in favor of removing /* */ comments, since i prefer to use // comments myself, and i don't like that my preference has competition. :)

[kiljacken]

While not a big deal with this exact feature, be careful not to go full APL "because editors can do better" :)

[andrewrk]

@kiljacken can you elaborate? I know you're slightly kidding but I'm taking your warning seriously.

[kiljacken]

Well, the story with APL is that it's reached a point of using abstract symbols for operations "because editors/keyboard can do better". It's reached a point (or well, have been at it for many many years) where you cannot feasibly code APL without a special keyboard or an editor specially tuned for APL.

That said, APL and Zig are very far apart from both syntactic and semantic standpoints, so the extent to which this can go bad in Zig seems rather limited.

As an aside, here is an example APL program, the one generating the first R prime numbers:

(~R∊R∘.×R)/R←1↓ιR

Beautifully dense, and quite expressive (if you know the symbols), but fairly impractical in your plain vim/emacs/nano/etc. :)

[thejoshwolfe]

I think we're all pretty much in agreement here, but just to follow up, the editor features we're designing for with this proposal are the rectangle select and rectangle edit modes that many general-purpose code editors already have today. Some editors are even more specialized with a feature for toggling comments (e.g. Ctrl+/ in eclipse JDT and CDT), but we're not designing for that kind of thing. We're not asking editors to design for us; we're designing for existing editors.

[thejoshwolfe]

This goal might be a lost cause though, since string literals can still cause this exact problem.

This is not true anymore. See #162.

Now every newline character in a .zig source file resets the tokenizer state, so a syntax highlighter can always be correct on a line-aligned excerpt of code.

[PavelVozenilek]

Embedded /* ... */ comments have good use in C, as the language does not support named parameters:
foo(1 /* this */, 2 /* that */, 3 /* ... */);
or inside complicated expressions.

There are people who prefer to provide documentation in form of very detailed comments (for example Doug Lea's allocator http://gee.cs.oswego.edu/pub/misc/malloc-2.7.0.c ) and the language should not fight them.

[marler8997]

Could support embedded comments another way,

foo(1 // this */);
// or
foo(1 // this //);
// or
foo(1 // this /);

[andrewrk]

You can still do that by using new lines and it arguably even looks better. There's also a proposal discussed on IRC for named parameters at the callsite. I'm not sure if that proposal has made its way to GitHub yet.