- effective documentation of macro header
- portable code for use with different OS
- error and warning message handling
- paper and online documentation
- use of nested macros and nested macro variables
- keeping macros simple for debugging
A little effort can go a long way towards creating a successful SAS macro. This paper will present tips and techniques that are not always obvious. Besides getting the resulting numbers to the user, a user friendly macro can enhance the entire experience.
SAS macros are great at automating repetitive tasks as a code generator. However, there are some features of macros that make them difficult to understand and debug. The syntax of SAS macros is similar to that of traditional SAS data step but there is a level of abstraction. To accomplish its code generating function, SAS macros add percent signs (%) and ampersand (&) in front of specified commands and variables. This layer can be confusing since it requires you to resolve the macro before understanding what is being processed. This confusion is compounded when things are nested. Macro variables can be nested by resolving into other macro variables. Macros themselves can call other macros which creates a nested looping structure. Macro code can sometimes be spaghetti code. It is therefore helpful for the user and the person maintaining the macro to make the macros user friendly.
One of the most straightforward ways to make SAS macros user friendly is to enhance the documentation that accompanies the macro. This is an essential part of software that some programmers overlook when delivering macros to users. There are many different forms of documentation and the more that is available, the greater the chance of connecting with the user. This paper will summarize eleven different types of documentation. The content can overlap among the different types but each method has its own strengths.
HTML – Documentation can be delivered as HTML pages within an intranet or Internet. This is readily available to all users. The website has the following advantages:
- Accessibility from any computer connected to the network.
- Hyperlinks to quickly navigate to specified content.
- Search engine to find specific content.
- Graphics for capturing screen shots and other diagrams for more effective communication.
PDF - Similar to HTML, a PDF file can be delivered within an intranet or Internet. Its strengths are similar to HTML with some distinguishing features:
- Can be delivered as one file, as in an email as an attachment, in case the user does not have network access.
- PDF format is more consistent for printing on physical paper.The content is locked from changes.