What is the difference between a release marker and a version number in a ado-file?

At the top of an ado-file, we see the following:

        *! version 10.0.0  28sep2007
        program define myprog
                version 12.0

The first line is a “release marker”, which is nothing more than a glorified comment. The "*! version 10.0.0" (note the * in front) comment says that, in our tracking scheme, we at StataCorp think of myprog as version 10.0.0. To find out what version of Stata it was written for, you have to look further down into the guts of the program for the version statement.

Second—and this is the important part—even if a program says version 12.0 further down, that does not mean it cannot exploit the features from later versions. For instance, a version 6.0 program can be used with sortpreserve, a feature added in Stata release 7. You do not have to change the version statement at the top of a ado-file to exploit a modern feature.

sortpreserve can be used with version 6 programs or version 5, all the way back to version 1. What the version statement says is, “in the case of a change in the interpretation of a statement, use the interpretation of the version specified”. version 6 does not mean “and lose the features of more modern versions”.

Changing the version statement of a working program is a dangerous thing to do. Consider a program that says version 9. You know it works with that language interpretation. If you change the statement to read version 10, you must also go through every subsequent line and ask yourself, “has anything changed that would cause this not to work as it did?”

In our own programs, we sometimes do this, but only when we are about to make many changes to the program. We tend to think the modern way (and forget the limitations of older syntax). Here we start by translating the program to the modern version, verify it works, and then make our changes.

Usually, the changes required are minimal, but it is not uncommon that changing that statement by itself breaks the program.

On the other hand, if the changes we wish to make are minimal, we leave the version statement alone because that is safer and easier.

version is one of the best features of Stata in my opinion. It allows us to improve the language without being hamstrung by prior decisions and without breaking existing software. Do not think that because a program says version 9 or version 10, it is not modern. A modern idea can be expressed in a bygone language.