Re: st: how to be -assert-ive

[wgould@stata.com (William Gould, StataCorp LP)]

Stas Kolenikov <skolenik@gmail.com> writes, 

> I wonder how often -assert-s are used in ado code? E.g., I know that
> some sort of -egen- command should retain the pattern of missing
> values from the source variable(s) [...]
>
> Now, I wonder if -assert-s in ado code is a desirable practice, [...]

At StataCorp, we rarely use -assert-s in ado code, although during the 
development process, we do use them, and we later remove them.  

I agree with Stas that -assert-s are a great way to verify that calculations
are going as expected, which is why we use them during the development
process.  Because official ado-files go through so much debugging,
verification, and certification, by the time we remove the -assert-s from the
code, we are convinced that the -assert-s are no longer serving any purpose.

I'm on record as recommending -assert-s in do-files.  StataCorp writes lots of
do-files for its own purposes.  We have do-files that look for broken links in
.sthlp files, do-files that verify tht distribution directories are complete,
do-files that produce reports on sales, and on and on.  Obviously those
do-files are full of -assert-s.  We also have a library of private ado-files
for use by those do-files.  Those private ado-files have -assert-s which are
never removed.

In some cases, the -assert-s are used simply to flag code that we thought 
would never need to be filled in, such as, 

        assert customer_type!="academic" if pricing_type=="business"

The official ado-files we write for Stata handle with every case.  Our 
private ado-files deal with cases we expect to arise.  We place 
-assert- in such cases so that, if we are every proven wrong, the 
do-file or do-files stops right there, thus alterting us to the problem.

For the same reason that we at StataCorp use -assert- in our private 
do-files and ado-files -- the reason being that such files are not 
subject to the extensive testing of Stata's production code -- I 
think it an excellent idea if users place and leave -assert-s in 
their code.  A few people may go the effort StataCorp goes to in 
testing their code, but most of us do not.

The problem with placing and leaving those -assert-s is the effect 
on execution time.  I have a suggestion.  Consider the following 
code snippit, 

        -------------------------------- myadofile.ado ---
        program myadofile
            version 11.1
 
            local verify               // <-- comment out this line 
            // local verify *          // <-- or this line 
            ...
            ...
            `verify' assert ...
            ...
            `verify' count if ...
            `verify' assert r(N)==...
            ...
            `verify' by `group': assert ...
            ...
         end
        -------------------------------- myadofile.ado ---

In the above code, local macro -verify- is set to contain nothing, or 
set to contain a *.  Depending on which way -verify- is set, the 
-assert- commands (and their associated code) run, or do not run.
Set -verify- to contain *, and the -assert-s are commented out.  

Here's another variation on the idea, 

        -------------------------------- myadofile.ado ---
        program myadofile
            version 11.1
            local verify = cond("$S_verify"=="", "*", "")
            ...
            `verify' assert ...
            ...
            `verify' count if ...
            `verify' assert r(N)==...
            ...
            `verify' by `group': assert ...
            ...
         end
        -------------------------------- myadofile.ado ---

In this case, local macro -verify- is set according to the contents 
of global macro S_verify.  if global macro S_verify does not exist (meaining
it contains nothing), -verify- is set to contain *.  Otherwise, -verify-
is set to nothing.

This makes it easy to turn off or on the -assert-s throughout the code.
At the command line, type -global S_verify on- to turn them on.  Type 
-global S_verify- to turn them off.

Both of these methods work with do- and ado-files, but do not work with Mata. 

-- Bill
wgould@stata.com
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/