Style guide for writing and polishing programs
From sasCommunity
A Modest Proposal for
A Style Guide for Writing and Polishing Programs
for Reading and Reuse or Testing
-- R. J. Fehd the macro maven 10:54, 7 May 2007 (EDT)
Contents |
[edit] Introduction: Why bother?
According to Brooks, in his book Mythical Man Month, half of program development time is spent in testing. This means that a program is bound to be read by other people, many times.
How is reading a program different from reading literature?
Literature is read sequentially; as the King said to Alice: "Begin at the begining, go to the end, then stop."
Programs are not 'read' with the same purpose as literature. Reading a program consists of three actions
1. Scanning for step boundaries or other blocks of code
2. Searching, or drill down, to statements within the block.
3. Checking off statements and options
Hint: alphabetizing keywords increases readers' searching speed.
[edit] Reasons and Benefits of Using a Style Guide
Professional Reasons:
1. You are a professional.
2. Professionals have a displine.
3. You practice that discipline, daily.
Professional Benefits:
1. Easier reading makes desk checking faster.
2. Clear layout makes testing and debugging faster.
3. Good documentation makes reuse easier.
Personal Benefits:
1. Faster development means you're finished sooner.
2. Finishing early or on-time gets you home sooner.
3. Sooner is better than later.
[edit] The Style Guide
[edit] Documentation
- Documentation: Requirements Specifications and Data Dictionary
- Documentation: Program Header
- Documentation: internal comments in program
- Documentation: of test suite of program, both unit and integration tests
- Requirements Specifications: http://en.wikipedia.org/wiki/Software_Requirements_Specification
- Data Dictionary: http://en.wikipedia.org/wiki/Data_dictionary
- Program Header documentation:
- Comments: http://en.wikipedia.org/wiki/Comment_%28computer_programming%29
[edit] Considerations while Typing
[edit] Case and Naming Conventions
- use lower case
Exception, use ALL CAPS for DATA, PROC. Note: this facilitates scanning a page for step boundaries.
Exception, use Initial Caps or InternalCaps for nouns: names of data sets, variables, arrays, macro names, etc.
See also Celko's SQL Programming Style for citation of why initalLowCase slows down reading speed.
- using underline as first character of names
SAS uses underline as prefix and suffix for temporary variables in data step, e.g.: _All_ _Error_ _N_
If you use underline as first character to indicate a temporary variable then you can use this statement to drop all variables whose first character is underline
drop _:;
[edit] Linesize, Spacing and Indentation
- maximum line length: 72
for cross-platform portability ensure that no text on a line extends beyond column 72.
- white space A Good Thing, but where and how much? The purpose of white space is to
- emphasize hierarchy: see indentation
- align similar tokens in columns
- newline vertically separates paragraphs
See rivers of white space http://en.wikipedia.org/wiki/River_%28typography%29 Celko addresses this issue in his book.
- tabs or spaces? use spaces; later readers may have assigned a different number of spaces per tab on their computer or editor which
effectively destroys your indentation
- indentation: use hanging indent style, indent word-1 of succeeding lines to align with word-2 in first line
Example:
* data step;
if SomeCondition then do;
Assignment1 = 'value';
Assign2 = value;
end;
* macro statements and else;
%if &SomeCondition1. %then %do;
%let Variable1 = value;
%let Var2 = value2;
%end;
%else %if &SomeCondition2. %then %do;
%let Variable1 = value;
%let Var2 = value2;
%end;
compare to:
*data step;
if SomeCondition then do; Assignment1 = 'value';
Assign2 = value;
end;
if SomeCondition then
do; Assignment1 = 'value';
Assign2 = value;
end;
if SomeCondition
then do;
Assignment1 = 'value';
Assign2 = value;
end;
Note vertical alignment of equals signs (=)
- Use Two.Level Data.Set Names
* note: illustrates procedure templates;
* and use of white space to align columns;
PROC Freq data = SAShelp.Class
order = frequency;
tables Sex
/ list missing noprint
out = Work.ProcFreqOutput;
PROC Sort data = SAShelp.Class
out = Work.Sorted
nodupkey;
by Sex;
[edit] Comments
- Comments: sas provides three types of comments:
/*comment block*/ *comment statement; %*macro comment statement;
Any of the above may contain multiple lines.
Note: macro comment statements may occur inside sas statements:
attrib RowID length = 4 %*integer;
Height length = 8 %*numeric real;
;
The slash+asterisk comment block is often used for banners:
/**************************************** This is a banner containing documentation ****************************************/
NOTE: In Operating System= MVS, z/OS, mainframe, or BigIron, slash+asterisk in columns one and two, as illustrated in the above banner, is interpreted as EndOfJob, or EndSAS.
Therefore a recommendation:
/******************************************** Ensure space on column 1 before slash+asterisk **********************************************/ ;/************************** ... or fill with a semicolon ***************************/
Slash+asterisk comment block is useful in debugging and testing since it can disable many statements. Therefore a recommendation: use sas comment and macro comment statements in your code, so that when you wish to use slash+asterisk comment block you will not be have small slash+asterisk comments closing your block.
[edit] Bibliography
sugi30.067, Ronald Fehd, Journeymen's Tools: The Writing for Reading and Reuse Program Header http://www2.sas.com/proceedings/sugi30/067-30.pdf Coder's Corner, 4 p.
sugi25.038, Ronald Fehd, The Writing for Reading SAS Style Sheet: Tricks, Traps and Tips from SAS-L's Macro Maven, http://www2.sas.com/proceedings/sugi25/25/ad/25p038.pdf Applications Development, 4 p.
sugi28.242, Dianne Louise Rhodes, Programming Standards, Style Sheets, and Peer Reviews: A Practical Guide, http://www2.sas.com/proceedings/sugi28/242-28.pdf Professional Development and User Support, 5 p.
sugi29.135, Dianne Louise Rhodes, Programming Standards, Style Sheets, and Peer Reviews: A Practical Guide, http://www2.sas.com/proceedings/sugi29/135-29.pdf Planning, Development and Support, 6 p.
sugi27.235, Dianne Louise Rhodes, Developing and Maintaining a Tips Database: A Practical Approach to Programming Standards, Style Sheets and Peer Review, http://www2.sas.com/proceedings/sugi27/p235-27.pdf Professional Development and User Support, 5 p.
sugi26.066, Ronald Fehd, A Beginner's Tour of a Project Using SAS Macros Led by SAS-L's Macro Maven http://www2.sas.com/proceedings/sugi26/p066-26.pdf Beginning Tutorials, 9 p.
sugi30.004, Ronald Fehd, Journeymen's Tools: Two Macros, ProgList and PutMvars, to Show Calling Sequence and Parameters of Routines http://www2.sas.com/proceedings/sugi30/004-30.pdf Applications Development, 8 p.
Steve McConnel, Code Complete http://cc2e.com/ Chapters: 35.
Fred Brooks, The Mythical Man-Month http://en.wikipedia.org/wiki/The_Mythical_Man-Month
Joe Celko's SQL Programming Style http://www.elsevier.com/wps/find/bookdescription.cws_home/705199/description#description Chapters: 10, 200 p., resources, bibliography, index: 20 p.
SAS-L post of 2007-Nov-29, Subject: Re: Learning to program better and in a more organized way http://www.listserv.uga.edu/cgi-bin/wa?A2=ind0711E&L=sas-l&P=R2184
- This page was last modified 20:18:50, 2007-06-07.
- This page has been accessed 798 times as of 2008-Jun-12
- This page was last modified 16:46:13, 2008-06-13.
- This page has been accessed 1,225 times as of 2008-Aug-21
