Date: Fri, 10 Oct 1997 08:56:05 -0700
Reply-To: "kmself@ix.netcom.com" <kmself@ix.netcom.com>
Sender: "SAS(r) Discussion" <SAS-L@UGA.CC.UGA.EDU>
From: "Karsten M. Self" <kmself@IX.NETCOM.COM>
Organization: Self Analysis
Subject: Re: SAS documentation methods/standards
Content-Type: text/plain; charset="us-ascii"
Ho-boy. The briar patch <g>.
Ask yourself some questions:
- What's your platform?
- What's your application.
- How large is the organization/development group?
- What is a typical development-maintenance cycle like?
- What are current development-maintenance issues/challenges (ok, plain
English: what's currently all f... up?)
- Do you have an application/development/toolkit base? Something like an
Autocalls library?
If you're embarking on the software quality/development rationalization
voyage, I very, very strongly recommend you purchase Steve McConnell's
"Code Complete" (Microsoft Press, 1993). The rest of the books I'd tell
you to look at are all mentioned in his excellent annotated bibliography.
McConnell covers all the essential elements of code building thoroughly,
in a general form -- the book emphasizes C and Pascal, but is quite
appropriate to SAS.
In terms of SAS, I'd make the following recommendations:
- Implement a code revision control system. Several commercial products
are available, one that's had good press, though I've never used it, is
Code Manager. I've had very satisfactory results with RCS, which is
commonly distributed with Unix (or available for free from your user
support organization -- bug your vendor). It has been ported to a number
of other platforms, including DOS, NT, Win95, VAX/VMS, etc. SCCS is a
similar, earlier version control package. Both are described in the
O'Reilly book "Applying RCS and SCCS" (see http://www.ora.com). The book
also discusses several extensions of these packages, including CVS and
TCCS. The last is the author's own product, and is not as fully developed
as the book leads you to believe.
- Use a standard header. Something including program name, program type
(e.g.: SAS program, SAS macro, Unix shell script), author, creation date,
purpose/usage/bugs, and (optional) the revision control log (this is
automatically inserted by the revision control software after a 'tag'
line). I've automated the creation of this, incorporated with revision
control initialization, most people simply have a standard which they copy
in to a new file.
- Follow a specify-code-test-release cycle for both new development and
maintenance. If maintenance results in significantly different code,
rename the program for backward compatibility. Discourage freelance edits
of production code. Tweakage of code in private libraries is allowable,
but the results should then be evaluated and approved, or rendered to the
scrap heap. Multiple versions of the same program are usually the start
of a problem.
- Separate code development from job production. Job production is runs
of SAS jobs. These serve different purposes, and have different
documentation needs and storage requirements. Job production should
involve as little modification of source code as possible, and ideally
none. This is possible through use of macros and/or GUI/windowed job
submission systems (AF/FRAME, or whatever fits your bill).
- Decide on development standards. Use code walk-throughs to enforce
them. Have the management buy-in to both make and enforce the standards.
Use the fewest number of simple standards possible, and be reasonable
with your expectations.
- Use macros. Put the standard macros in your autocalls path(s) or a
macro catalog. Autocalls allow viewing source, catalogs may be used to
discourage it. Both methods have their appropriate applications. In the
"I still learn new things from SAS-L" dept., the /DESC switch can be used
to add free-text descriptions to macros.
- For batch-oriented SAS jobs, try to develop encapsulated,
parameter-driven macros using named parameters. Typically you specify
inputs, outputs, runtime parameters, and debug options. Think of these
macros as if you were developing a new SAS procedure (which you are
doing). Try to keep these simple and consistent. I also recommend
in-line comments describing the parameters:
%macro myjobmac(
input1= , /* primary input table containing wigits */
input2= , /* secondary - widget in-law lookup */
output= , /* output dataset */
report= , /* report hardcopy, text file, full path */
graphcat= , /* graphics catalog */
colors= , /* widget colors to run */
multiplr= , /* multiplier factor */
debug= true , /* debug switch, sets MPRINT, MLOGIC, SYMBOLGEN if not
false */
) ;
- For function-equivalent macros (macros which return an expression for
use in a data step or SQL statement), try to emulate SAS function styles.
This usually means positional, rather than named parameters, though I
will violate this rule (in favor of named) with complex logic:
%macro gt( arg1, arg2 );
( &arg1 gt &arg2 )
%mend;
Anecdote. After hearing an NPR Talk of the Nation show concerning Y2K
issues, with Kathy Adams, the Social Security Administration's Y2K lead, I
asked what factors contributed to success. After staff issues (very high
retention, strong dedication), the technical solution was "Structuring
and optimizing our COBOL software and instituting good configuration
management and library systems." With a 30+ year legacy of COBOL and
assembler code, which we all trust to work when we don't, very few other
"modern" development techniques were applicable. The task largely
involved fixing existing systems rather than rewriting, though both
methods were applied.
On Tuesday, October 07, 1997 12:04 PM, hootspa1 [SMTP:hootspa1@TIAC.NET]
wrote:
> I am taking a first look at this for my org.
>
> Anyone have any pointers, examples, are any other resources that might
> help??
>
>
> -hootz
Karsten "Br'er Rabbit" Self (kmself@ix.netcom.com)
What part of "gestalt" don't you understand?
| 
