Right, * is a comment marker, but should it be used?
There are two other ways to mark your comments in Stata, each useful
in its own way:
One is the double forward slash: //
It has the small advantage that you can use it both in a stand-alone
line, like you would *, and at the end of a command, like
save myresults, replace // and here they are
But the main argument in favor using it instead of * for one-line
comments is that it's unambiguous. It can only mean in-line comment,
not also multiplication. The current publicly available Stata language
definition sheet for Notepad++, written by Keith Kranker, treats // as
a comment delimiter and turns everything that comes after it on the
same line into gray italics (you can change that, of course). It tries
its best to do the same with *, but here the ambiguous meaning will
bite you. The language definition sheet has to tell apart somehow
multiplication and comment, and its default behavior is that "* means
comment if followed by a blank space; it means multiplication
otherwise." So if you like your arithmetic operations with spaces
before and after operators, like so
a = b * c
then the last c will show up in gray italics in Notepad++ (though
Stata, of course, won't be fooled).
If instead you like your inline comments without a space between the *
and the first word, like so
*file this for future reference
then this will not be italicized. In addition, both "file" and "for"
in this string will be color-coded as if they were Stata commands.
Again Stata will correctly treat this as a comment, but in Notepad++
it won't be easy on the programmer's eye. Of course this is moot if
you're using an editor that can correctly define * as "comment
delimiter if found at the beginning of a line; multiplication sign
otherwise".
The other comment delimiter is /* */. This, I think, should only be
used for bypassing code while you're drafting your do-file. When you
know what you want to keep, delete that bypassed code altogether.
/* */ looks atractive because for multiple comment lines it saves a
lot of work, but I think that if you have to type // in front of every
comment line you will be forced to choose your words well. Generous
comments are good, but they shouldn't be too verbose.
Having these two comment delimiters available, I really don't see any
need for *.
Gabi
On Fri, Sep 26, 2008 at 5:02 PM, Nick Cox <[email protected]> wrote:
Whatever is undocumented is not documented.
However, "not documented" means what you expect it to mean from ordinary
English, while "undocumented" has a specific Stata sense of what is
undocumented in the manuals but documented on-line via -help undocumented-.
If you read this backwards while standing upside down and looking in a
mirror, it makes more sense.
Nick
[email protected]
Eva Poen wrote:
I find -help undocumented- contradictory...
