Comments

[zygoloid]

Lexical syntax for comments.

• Proposal PR
• RFC topic
• Decision topic
• Decision PR
• Announcement

[jonmeow]

Trying to avoid style comments since it's just a proposal doc, let me know if you want style comments...

[josh11b]

We seem to have agreed to try this last sentence out, but it seems more likely to change than other parts of this proposal -- is there a need to mark this as provisional or experimental?

[zygoloid]

Yes, that's a good idea. Done.

[josh11b]

My answer: yes.
To me, picking either one is better than choosing both.
I'd rather pick one and switch if we decide that we picked the wrong one than have both.

[zygoloid]

OK, I'll run a poll in #syntax to gauge consensus.

[zygoloid]

Based on subsequent discussion, I'm no longer proposing to handle documentation via comments. I think that resolves this comment thread.

[josh11b]

I think we should go further and specify a format for doc comments? I saw this recent thread on HN where people were pretty happy with Rust's approach of using markdown with Rust-specific extensions, such as the ability to link to language symbols, not just URLs: https://news.ycombinator.com/item?id=25149969

[gribozavr]

I agree and support this direction, but it might be better to leave details to a separate proposal.

[zygoloid]

Added an open question for doc comment formatting.

[josh11b]

because it doesn't start at the beginning of the line?

[zygoloid]

Yes.

[josh11b]

Please clarify that in the text.

[zygoloid]

Resolved by removal of this section.

[jonmeow]

As I went through commenting, I decided I really want a clear proposal on whether block comments or repeated line comments should predominantly be used for long comments. There are a few comments touching on this, and I made the comment on line 104 at the end to be unambiguous.

[geoffromer]

There's a use case that seems to fall into the cracks between doc comments and block comments: Sometimes it's useful to provide at least part of the documentation in the form of a block comment, so that it can be cut and pasted without having to manually remove // from the beginning of each line, e.g.

/*
For example, this program can be run with:

a.out --flag --other_flag --yet_another_flag \
  --flag_name_that_pushes_us_over_80_characters
*/

Any thoughts on whether/how Carbon could support this use case? It seems like it might work better if we use string literal attributes instead of comments for documentation.

[zygoloid]

Based on prior discussion, my expectation is that we'll have a string-literal syntax for documentation, including support for block string literals. I'd expect that such support could be used here. Eg:

#"""
This program can be run with:

```
a.out --flag --other_flag --yet_another_flag \
  --flag_name_that_pushes_us_over_80_characters
```
"""
package Foo impl;
...

[jonmeow]

What other languages that don't provide block comments? It looks like Visual Basic and R don't, although VB has IDE assistance for block commenting code and is essentially an IDE-only language. I'm very wary of this experiment -- I don't think we should pursue it, it feels like it will create a barrier for Carbon adoption by C++ developers due to poor ergonomics.

[zygoloid]

Python has no block comments.

The rationale for including block comments was incredibly weak. Consensus seemed to be that we didn't want block comments for human-readable text, and the only remaining use cases were for commenting out code transiently during development and for bisecting compiler test cases. (It seems the Go folks have come to the same conclusion: https://www.digitalocean.com/community/tutorials/how-to-write-comments-in-go) So we're left needing to justify the inclusion of dedicated language syntax for that purpose, which is challenging when the existing comment syntax can be used to achieve the same thing.

Regarding IDE assistance, I think there's a large spectrum between IDE-only languages and languages whose code can be effectively maintained in notepad, and while I agree that we don't want an IDE-only language, I don't think this pushes us too far in that direction. But I don't know -- that's why I consider this experimental. If there is a barrier, we can find that out and adapt, probably long before there's anyone writing Carbon code other than ourselves. If there isn't, we'll have added a feature we didn't need, and we probably won't ever find that out.

In general, given that it's much easier to add language features later than it would be to remove them later, presenting a more minimal feature set initially supports our language evolution goal.

[jonmeow]

While Python doesn't technically do block comments, it does allow """ string literals in places where it's a no-op (something I would assume we'd treat as a compile error due to the lack of side-effects). (and I have had issues with Python due to this, it makes it a nuisance to comment out large amounts of code with docstrings)

Regarding Go, I think the best reference is the official "Effective Go" docs: "Line comments are the norm; block comments appear mostly as package comments, but are useful within an expression or to disable large swaths of code." So they do note use for human-readable text.

Note, I'm fine if we disagree with this stance, I just thought I'd speak up with trepidation.

[zygoloid]

OK. If nothing else, this is something we should make sure the core team explicitly considers as part of their decision.

[austern]

I'm slightly nervous about leaving out block comments too, just because they're present in so many language. (Including C++ and all of the languages anyone talks about as potential replacements for it.) On the other hand, the comment from zygoloid earlier is pretty persuasive: this is an easy decision to reverse if anyone finds it too annoying.

[zygoloid]

Acknowledged. Would it improve this proposal if I made the question "do we want to run the no-block-comments experiment?" an explicit open question for the core team? I expect the core team will consider and discuss this part of the proposal -- probably more than anything else -- either way.

[chandlerc]

Just wanted to say this proposal generally LGTM. I'm very nervous about not including block comments at all, but I also don't think it's really worth trying to figure out right now and it does have the advantage of being wonderfully simple.

[chandlerc]

I think essentially all of my questions are addressed. Some more editorial suggestions below - mostly I find the term "maintenance comments" not working well for me. I've listed a potential alternative, but maybe thats only better for me...

[chandlerc]

Maybe make this a bit more precise:

Suggested change

	- _Documentation_: human-readable commentary explaining to users and future
	- _API documentation_: human-readable commentary explaining to users and future

[zygoloid]

(See below.)

[chandlerc]

Will resolve either way (based on the resolution below).

[zygoloid]

I believe this is addressed now.

[chandlerc]

With the above, maybe:

Suggested change

	- _Maintenance comments_: human-readable commentary explaining intent and
	- _Implementation documentation_: human-readable commentary explaining intent and

It doesn't seem exclusively about maintenance, but about documenting the behavior / logic / rationale / etc of the implementation.

[zygoloid]

The line I'm trying to draw would classify (for example) comments on private members of a class or a function that's an implementation detail as "documentation" but (for example) comments in a function body as "maintenance comments". Broadly, if we imagine an automatic documentation generation tool in a "generate internal documentation" mode, or an IDE that displays documentation, I'm trying to classify the things that such a tool would care about as "documentation" and the other comments as "maintenance comments". I think renaming the latter category to "implementation documentation" would make the distinction less clear, because those are comments that you would not translate into machine-generated code documentation.

Part of this is framing the background in terms that fit the proposal: I'm trying to position the terminology here so the things we write as @"..." (straw-person syntax) are always called documentation and never called comments, and the things we write as // ... are always called comments and never called documentation. That's how I'd like us to describe things going forward, if this proposal is accepted.

That being said, yes, you need to take quite a broad interpretation of "maintenance" (including, for example, reading the code with no intent to modify it) for this to really describe the entire purpose of such comments. Would "implementation comments" work better here?

I have no major concerns renaming "documentation" to "API documentation", except that it seems redundant if we don't also rename this one to "<something> documentation", which I'm reluctant to do for framing/pedagogy reasons. I'd also be a little concerned that people will see "API" and think exclusively "public interface".

[chandlerc]

Happy with "implementation comments", and that makes me not care whether you include "API" above.

[zygoloid]

Renamed to "implementation comments".

[austern]

I'm slightly nervous about leaving out block comments too, just because they're present in so many language. (Including C++ and all of the languages anyone talks about as potential replacements for it.) On the other hand, the comment from zygoloid earlier is pretty persuasive: this is an easy decision to reverse if anyone finds it too annoying.

[austern]

I also have misgivings about requiring whitespace after "//", since it's a seemingly unnecessary difference from C++. But again, it should be relatively easy to fix if it turns out to be too annoying.

[zygoloid]

Now we've abandoned all of our past uses of this lexical space, and don't have any immediate plans to add new uses, I don't think there's a pressing need to keep it reserved. But if we think there's any chance we might want new comment flavors in the future, keeping this syntax reserved seems marginally useful. Do we think this is going to frustrate people in practice? I could imagine people wanting // with no following whitespace for commenting out code in particular.

Perhaps we should describe this restriction as experimental too?

[austern]

That probably makes sense. This comment, too, was motivated by the question of automatic C++-to-Carbon translation. I'm thinking of cases where people use ASCII art for comments, in which case the requirement to add a ' ' at the beginning of some lines would lead to a lower fidelity translation than we might otherwise have.

[austern]

It might be worth saying something about what an automatic C++-to-Carbon translator should do with comments under this proposal, given the more restrictive placement. (Or is the idea that we shouldn't expect C++ comments to get transferred to the Carbon version verbatim?)

[zygoloid]

I don't think I have a solid answer here, but I do think it's important that we translate comments in the common case.

Comments at the start of a line seem straightforward to translate, and I'd imagine we'd make a policy decision that we produce documentation whenever a comment appears at a suitable position. Trailing comments seem slightly harder, because there's the risk that they aren't directly associated with the line to the left:

int left;  // The location of the widget relative
int top;  // to its closest ancestor.

But I think we can get a 95+% conversion by moving these comments before their declarations.

Comments in unusual places (specifically, neither at the beginning nor at the end of a statement) seem likely to cause problems for translation irrespective of whether we permit intra-line / block / trailing comments in Carbon. I don't really have a good answer there. Tracking where they are in the C++ AST and mapping that into the Carbon AST seems like it may be infeasible in general. I expect such comments would also be a problem when migrating between versions of Carbon, although likely less so, because we'll hopefully mostly be doing localized rewrites rather than full-source-file rewrites.

I'm happy to include something along these lines in the proposal, though I wonder how much detail we should go into here versus in a proposal more targeted at migration. Maybe this is something we should be systematically asking of all proposals involving language syntax?

[austern]

You're probably right that this is something we should be systematically asking of all proposals involving language syntax. Or to make a slightly weaker claim: this is something we should be systematically asking of proposals involving language syntax in all cases where there's reason to think translation might be problematic.

I asked in this case because the proposed Carbon comment syntax is more restrictive than the existing C++ comment syntax, which makes me wonder if there would always be a good Carbon translation for C++ comments. I think there's a chance, once we start writing a C++-to-Carbon translator, that we'll find it's easiest to allow Carbon comments in all of the places where C++ comments are allowed.

[chandlerc]

FWIW, I'm pretty happy here (if, like others, nervous about block comments).

[chandlerc]

Happy with "implementation comments", and that makes me not care whether you include "API" above.

[chandlerc]

Will resolve either way (based on the resolution below).

[jonmeow]

Approving per responses at https://forums.carbon-lang.dev/t/request-for-decision-comments-198, working on decision...