Documenting sas programs

Hello All,

I am interested to hear any suggestions for documenting sas code..I
have found Rolands tip page to be extremely useful
(http://www.datasavantconsulting.com/roland/sastips.html), but was
wondering if you all had more insights in terms of what to include in
documentation..

The catch is, the programs i am documenting are for sas inter/net
applications..So do you typically include html form names etc..that
invoke the program? any other suggestions of what to include will be
helpful..

I realize that documenting is sort of a matter of personal preference,
but i would like to know what others tend to do..

PS..Examples would be wonderful...

Thanks, Nevin

"nevin" <nevinkrishna@hotmail.com> wrote in message
news:1107537616.749456.144240@z14g2000cwz.googlegr oups.com...
> Hello All,
>
> I am interested to hear any suggestions for documenting sas code..I
> have found Rolands tip page to be extremely useful
> (http://www.datasavantconsulting.com/roland/sastips.html), but was
> wondering if you all had more insights in terms of what to include in
> documentation..
>
> The catch is, the programs i am documenting are for sas inter/net
> applications..So do you typically include html form names etc..that
> invoke the program? any other suggestions of what to include will be
> helpful..
>
> I realize that documenting is sort of a matter of personal preference,
> but i would like to know what others tend to do..
>
> PS..Examples would be wonderful...
>
If you're talking about comments within a program, my general standard is
that someone should be able to read the comments and understand what the
code is doing. No one should have to read the code unless they are going to
change it.

Essentially, the program should be written in English (in my office anyway,
and that means not in "pseudocode") as well as in SAS. If sufficient
documentation is contained in some document or other, the in-code comments
can be brief statements referencing the external document.

In article <1107537616.749456.144240@z14g2000cwz.googlegroups .com>,
"nevin" <nevinkrishna@hotmail.com> wrote:

> Hello All,
>
> I am interested to hear any suggestions for documenting sas code..I
> have found Rolands tip page to be extremely useful
> (http://www.datasavantconsulting.com/roland/sastips.html), but was
> wondering if you all had more insights in terms of what to include in
> documentation..
>
> The catch is, the programs i am documenting are for sas inter/net
> applications..So do you typically include html form names etc..that
> invoke the program? any other suggestions of what to include will be
> helpful..
>
> I realize that documenting is sort of a matter of personal preference,
> but i would like to know what others tend to do..
>
> PS..Examples would be wonderful...
>
> Thanks, Nevin

Seven or eight years ago I presented a paper at a SAS conference about
this very thing. It was very well received. I did it for my own benefit,
because I'm not always a good documenter. But because I did a paper on
documentation, I've set up myself up on a pedestal from which I can't
afford to fall off.

Here's the bulk of the paper:

Laurie Fleming
Sysware Consulting Group Ltd
Wellington

Introduction
The main theme of this conference is Finding Diamonds in Your Data -
what documentation can achieve is the ability to reveal diamonds in your
coding structure.

Everybody at least pays lip-service to the idea of documentation, but in
my experience as a maintenance programmer it is rarely done well, if at
all. Sometimes it is done much after the fact, which can be as bad as
not doing it at all.

I'm talking here mainly about internal documentation; external
documentation is primarily in the domain of technical writers, and
doesn't often become primary source information for maintenance purposes.

What internal documentation isŠ
The documentation I'm referring to is that which lies directly within
the code and datasets, and although not executable, in a way becomes
part of it. SAS code has myriad ways of making things happen, often in
the most obscure ways. Take for example this line (in macro code):
%let j = %substr(000&j, %length(&j),4);

Without something to explain what this is doing, somebody seeing it for
the first time would spend some time poring over it to find out what j
is having assigned to it. It is in fact simply right-justifying and
zero-filling a value of j up to four characters.

The explanation of SAS code can often take up more space than the
writing of it in the first place. This is not a bad thing; I commonly
find that around half of a block of code is documentation, but I am
secure in the knowledge that, when I may next see that code in six
months, I will immediately get a handle on its methods.

Looking through the book that contains the papers at [1997's] SAS Users
Group International Conference (SUGI 22) I was dismayed to discover, in
the great majority of mostly excellent contributions, that few of them
had more than the most cursory internal explanations as to what the code
was about. I understand of course the limitations in displaying code in
a two-column layout such as this, but I found through reading the code,
if the documentation were lacking, that I very quickly lost interest
because of the sheer effort required to comprehend what was going on.

If I were called on to maintain this code, I would have to set aside
much more time getting to grips with its internals, and thereby be less
confident that I had made the right choices in any modifications I had
made. With documentary signposts the job is shortened, with a greater
chance of success and user satisfaction.

Documentation prescription
A few years ago I was commissioned to do a short-term job for a company
to internally document their code. There was ample external
documentation, mostly of a very technical statistical nature, but the
internal documentation was almost completely lacking. Although I had of
course, lest I be thought hypocritical, previously documented my code
pretty thoroughly, this was the first time I had formally set down a
standard for documentation. Here is my current documentation style, with
appropriate explanations.

1) Create a header at the top of every programme to show:
a) Who wrote it
b) When it was written
c) Who it was written for
d) SAS input and outputs
e) Other inputs and outputs (flat files; external databases)
f) Macros used
g) Formats used
h) Other SAS code called
i) Where called from
j) Other dependencies
k) Brief overview (couple of sentences) of what the code does
l) Structural overview, showing what each step in the code does.
m) Modification history, preferably in reverse chronological order,
showing who made the change, when it was made, and a brief explanation
of what was done.

These are not hard-and-fast rules; indeed I break them regularly myself.
The intent is to provide enough generic information about the code so
that whoever takes it over knows who to blame and possibly where to go
for more information.

2) At the head of each physical or logical step, place a comment
bounded by /* */ to show what that step does. My preferred style is:
/*
Sort the view to a new dataset by id, removing
duplicates.
*/
with a blank line preceeding, because - well - I like the way it looks.

Note the use of white space - this does increase the size of the code
considerably, but creates a physical barrier between blocks of code. It
also makes it more restful on the eye, because it means there's less
information to take in when scanning the code. I find using any more
blank space than this can make the code hard to scan, especially on a
low-resolution (25 lines or less) screen.
3) Put more comments inside data steps if they are particularly long or
involve particularly complex processes.
4) Add /* */ comments to the end of single lines, if it is possible to
express an explanation in a few words.
5) Avoid use of * ; and %* ; comments, because they often can
contribute to bugs, especially if the comments semi-colon is missed offŠ
6) Include explanations at all times, even when the code appears
completely self-evident - there is a much better-than-even chance that
in a very short while the code will no longer appear self-evident and
bring about much scratching of heads.
7) Don't be restricted to placing comments in the code itself; SAS
provides several excellent methods for documenting SAS entities, whether
they be data sets, macros, views, cataloguesŠ :
a) data repos.mar97 (label='March 97 data for Repository system');
b) %macro sybclone / des='Create clone of Sybase table';
c) attrib acopdte length=4 format=ddmmyy8. informat=ddmmyy8.
label='Date account opened';
8) Consider using a footnote at the beginning of a programme, showing
some details of who wrote the code and where it's stored. This can be an
extremely good reference if all the user can show the maintenance
programmer is a report, but that report contains a pointer to its
generation. For example:

footnote "Author: Laurie Fleming. Stored:
~flemingl/sascode/audit_report.sas";

Non-coding documentation
This above example of attrib is interesting, because it can still be
used even when it belongs to variables that aren't being kept at the end
of the data step; its use in this case could become clear while looking
through the code trying to find how a date variable at the end of a
programme was derived, and finding that it came originally from a
variable with a cryptic name: acopdte. With SAS's current restriction
[v6.12] on variable names having only eight characters, it's sometimes
difficult to make a meaningful name. With a label statement or clause,
along with the format and informat, its inherent meaning is clear.
Having forty characters to play around with isn't perfect, but it's much
better that eight.

Another advantage of using the label and similar clauses is when using
the dir, var, catalog and similar windows - these can be a great aid in
understanding code.

Simply defining all variables in a dataset, even with just a length
statement, or %localing and %globaling macro variables, rather than
letting them default to types and lengths and scope, can be a great help
- little differences that can make your successors life much easier.
One of the greatest non-procedural debugging aids, alas, disappeared at
the end of version 5 of SAS - when using PROC CONTENTS on a dataset it
listed out the code that generated it. This was a wonderful boon when
investigating old datasets when the code was difficult to find or even
non-existent. I would be the last person to promote the continued use of
version 5, but I am rightly nostalgic for this great tool.

Conclusion
Documentation is relatively easy to do, as long as it is written at the
same time as the original code - if left later it is often difficult to
work out what some of the more obscure code means.

Descriptions of code can often take up more space than the code itself.
For an example, see the part where the log is read in the accompanying
code.

It can greatly decrease maintenance costs both in money and time,
because the job of the maintenance programmer becomes simpler.

The documentation must be kept up to date - if it badly reflects the
code, it's actually worse than useless because it misdirects the
maintenance process.

There is even an æsthetic to documentation - if well spaced out and
formatted it can make the whole code look more attractive. If it looks
attractive, it probably means that the programmers who worked on it
previously took time and care over it.