[Date Prev][Date Next][Thread Prev][Thread Next][Date index][Thread index]

Re: st: undocumented command *

From   Nick Cox <[email protected]>
To   [email protected]
Subject   Re: st: undocumented command *
Date   Fri, 26 Sep 2008 17:07:52 -0500

Sorry, but this seems backwards to me.

1. The apparent difficulty of getting one external text editor to recognise Stata's syntax properly when highlighting does not weigh heavily as a general constraint on everyone's coding practices.

2. Declaring a personal preference against * is fine by me, but as also explained it is not the only option, so feel free not to use them then. The same comment applies about the general situation with extra force.

3. In general, there has to be a really, really good argument for abandoning anything in Stata, even with mechanisms like version control.
If we went back in a time machine to 1984, I think I would you join in suggesting not to use * in this way, but that's clearly fantastical.

[email protected]

Gabi Huiber wrote:

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

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 *.


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.

[email protected]

Eva Poen wrote:

I find -help undocumented- contradictory...
*   For searches and help try:

© Copyright 1996–2024 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index