Multi-line comments coming back to life (bug or feature?)

[Daniel Kraehmer]

Dear Statalist community,

As documented in the help, the asterisk (*) "indicates that the line is to be ignored." Until very recently, I never encountered any exception to this rule. However, somewhat surprisingly, the obliterating capacity of the asterisk seems to spare multiline comments. The following code illustrates what I mean:

sysuse auto.dta, clear

* I would expect the following two commands to execute, even if I type: ///
sum price
sum weight
* However, only "sum weight" is executed (i.e. the multine comment is in effect)

* The effect of /// remains, even if the characters occur somewhere in the middle
sum price
sum weight
* Again, only "sum weight" is executed

* The effect of /// disappears when a blank line is inserted

sum price
sum weight
* Finally, both "sum price" and "sum weight" are executed

* Similarly, the asterisk does not deactivate the opening comment /*
sum price
sum weight
These commands are not executed, although Stata's do-file editor does not flag them as comments.

Is this a bug or a feature in Stata? Intuitively, I see no reason why multiline comments should be exempted from the obliterating effect of asterisk comments. If this is by design, are there any other commands that escape the scope of asterisk comments?

I am using Stata 17 on Windows 10.

[Nick Cox]

Good question.

In a do-file or program, you can start a comment with * and if it ends with /// then the next line is regarded as part of the same comment -- all part of the idea that multiline comments are allowed in do-files and programs.

This isn't a bug as far as Stata is concerned, as there are two rules in operation there and they don't contradict each other.

Whether that's a surprise depends on your expectations.

I wouldn't call it a feature as I can't think of a deliberate use of this that is positive. That is, a person reading the code could easily be puzzled at the intent, and me too on first reading #1.

Interactively, * starts a comment and /// within the same comment is ignored. This could be regarded as an inconsistency, but the way I think about it that multiline comments are not supported interactively, and so Stata ignores what you say in a comment, which is for people reading it only. Stata's not on the lookout for /// interactively.

Interactively, you can type a series of comments beginning with *, but syntactically, that is a series of one-liners. Authors and readers are free to think that they are reading a multiline comment, but that is not correct as a matter of syntax.

[Daniel Kraehmer]

Thanks for the quick reply and clarification!
I guess my confusion arose from the assumption that Stata would process any code strictly from left to right (in which case the asterisk should have overruled any subsequent multiline comment).

[Clyde Schechter]

But doesn't O.P.'s code demonstrate a bug in the do-editor? The do-editor is supposed to color-code commented out material. But it fails to do so in all of his examples, except the one where a blank line follows ///, in which case there are no commented out commands.

I would even consider it an important bug. It should be possible to distinguish executable from non-executable material at a glance in the do-editor by virtue of color.

[Hemanshu Kumar]

I agree that the do-file editor should reflect this behaviour. It would be good if OP could inform Stata technical services about this.

[Leonardo Guizzetti]

I lean towards this being a bug, though I can see the logic from Nick's post above. Only StataCorp can make this decision. I actually wouldn't have even tried to make a multiline comment using * and /// together. The /**/ style of comments are more natural for multiline comments.

I view this from the perspective of what is documented under -help comments-. Under the Technical Notes section, the behaviour of /// is clearly explained, in that, it ignores the rest of the line (treating anything that follows as a comment) and then joins up with the next line. From the examples given, the intended use is then for whatever follows on the subsequent line to be executable code. From this perspective, it is consistent with the behaviour of the syntax highlighting in the do-file editor (though again, not illegal from the interpreter's perspective).

[Daniel Kraehmer]

Brief update: I reported the issue to StataCorp and they will review if the editor's syntax highlighting can handle the slashes better.

In terms of code execution, Nick Cox was right to say that Stata is behaving correctly by extending the line due to the /// - so the next line is commented out (which I, personally, still find somewhat counterintuitive).

[Chinh Nguyen (StataCorp)]

The behavior is correct and intentional. /// is typically used to make long commands more readable by splitting them up into multiple lines. Imagine you have this code:

replace final_result =                 ///
   sqrt(first_side^2 + second_side^2)  ///
   if type == "rectangle"

You want that treated as a single line. Putting a * in front of it allows you to comment the whole command out without having to put a * at the beginning of each line or putting /* */ around it.

We will look at updating the Do-file Editor's syntax highlighter to support this as adding /// at the end of a comment was not an expected use case.

[Hemanshu Kumar]

I find it interesting and commendable that the "Stata Enhanced" extension (by Kyle Barron) for VS Code colours the lines correctly (as per Stata's actual behaviour) even though Stata's own do-file editor does not.

[Daniel Kraehmer]

To close this thread (with some delay): StataCorp fixed the Do-file Editor's syntax highlighting in Stata 18, update 30aug2023. See:

whatsnew18

Thanks for the fruitful discussion!