The below is a short abstract from Veramed’s Good Programming Practice guidelines. Download the full guide using the link on the right.
The purpose of this Guideline (GUI) is to provide guidance for good programming practices (GPP) for analysis, reporting and data manipulation of clinical data in health and life sciences organisations. This guidance is primarily aimed at programming in SAS, however the principles of GPP also apply to other languages such as R and Stata. In addition, although this is not produced with SAS macros in mind, the same principles apply to macros too.
We often have to update existing programs to add new rules, copy programs from one study to another, and take over programs written by others. The guidance aims to show how to produce well structured and well documented programs so that they are easy to read and maintain over time. It is meant to be applicable to all programs, and hence all programmers regardless of experience. Specific rules may be of more use to novice programmers, but applying the principles should be in mind for experienced programmers and mentors.
Comments are important to help anyone reviewing, modifying or using a program to be able to quickly understand the code. All major data or proc steps should be commented, especially data specific and complex code. Ideally comments should be comprehensive, and should describe the rationale and not simply the action. For example, instead of simply typing “Access demography data”, describe which data elements you are accessing and why they are needed, for example, “Bringing in DM to get gender and age and subset to include only the intent to treat population”. Comments can also include links to external documentation (requirement specifications, design documents. The programs should also be split up into sections by creating different types of comments, e.g. many rows with asterisks. This helps to structure the program and make it easier for others to see an overview of the program.
Further guidance from Veramed
- Consider the most appropriate method of commenting for the placement of the comment. For example macro comments should be used in macro code, block comments should be avoided in favour of line comments.
- Use a consistent style of commenting throughout the program.
- Write comments as if someone new to the project was looking at the code.
- Avoid punctuation marks that may cause syntax errors. Grammatically incorrect English is acceptable!
- Include comments at appropriate places in the program in order to aid clarity.
- Explain subsetting.
- Identify the activity being performed.
- Explain the reasons behind the coding.
- Ensure comments are consistent with the code they are explaining. If the code is updated, ensure the comments are too.