Feature request: scoped comments

[vissermc]

The main reason comments rot is because they are not part of the syntax tree, making what they are referring to ambiguous.

Proposal, the 'because' keyword.

because( this is human readable text )
{
// code
}

and:

x = y + z because( this is human readable text );

and:

{
// code
} because( this is human readable text);

[L4stR1t3s]

// and /* */ comments are removed by the preprocessor before compiling. This can easily be done because any time you encounter // you remove until the end of the line. and any time you encounter /* you remove until the next */.
By making it part of the syntax, this preprocessing will require more complicated parsing, or you leave the comments until the compile step and remove them there. Either way, this will come with a compile time performance cost.

I am also not convinced this will improve the quality of comments. Nothing prevents someone from changing this line of code:
auto z = x + y because (the sum of x and y is required here);
to this line of code:
auto z = x - y because (the sum of x and y is required here);

[vissermc]

Using comments to repeat what the code is doing is a code smell. Comments should only be used when information is needed that cannot be inferred from code.

[matta]

The main reason comments rot is because they are not part of the syntax tree, making what they are referring to ambiguous.

I am having trouble coming to agreement that this is the main reason comments rot.

My intuition is that most comments rot because sufficient care was not taken to update the comments when individuals edit code. Key point here is that humans almost always know what each comment refers to.

When tools modify code, they can sometimes fail to place existing comments in the correct place. Here I can see value in formalizing how comments relate to specific code constructs. Even without something as explicit as because, formalizing this may be worthwhile to encourage consistency in Carbon tooling (i.e. formalize how tools should treat comments in their AST).

Have a look at https://github.com/carbon-language/carbon-lang/blob/trunk/proposals/p0198.md, which explains the current thinking on comments. The interesting thing I see there is that comment lines must be preceded by white space only (which is unusual), and that an entire class of comments (such as those that appear at the end of a scope) are intended to be rendered unnecessary with clearer language grammar.

[vissermc]

The current thinking on comments is still comments are not part of the syntax tree. And you seem to agree this is giving problems for refactoring tools. AND also for humans. Scoping comments will give programmers much cleaner intuition on which comments they need to update. Thus: less rot.

[YagaoDirac]

Comments should be also involved in ast. Also, all the white spaces.
This allows bidirectional generation between code and ast.
Then the upgrade tool could focus on only ast. I mentioned this in my old thread.#1572 the 9,.

[micttyl]

Like other languages, one can use few available documentation generators and they work similarly. Is this what you are talking about?

[vissermc]

Document generation is only done at function/interface level. This feature is about the functional code, and not the interface. It might be a good idea to have a separate feature to also make interface comments part of the systax tree. For example, we could claim the keyword 'meaning'. Example:

fn Main() -> i32 meaning(result) {

} meaning(initiate memory and threads)

[urielgarciarivas]

What you are proposing would be equivalent to do, in a C++ code-base:

variable.code();

// because (this is human readable text) {
    variable.code();
// }

variable.code();

Please note the unnecessary indent in the fourth line. You can achieve the exact same thing if you only do, in Carbon code:

variable.code();

// because (this is human readable text) {
variable.code();
// }

variable.code();

Without actually getting into over-indenting code to cover a block of code with one comment.

[vissermc]

You are missing the point. Comments in c++ or Carbon are not part of the AST. So it is only equivalent in the sense that it doesn't do anything, but it is from the developer side or IDE side completely different.