“I don’t document my code because if you really understood the language, it should be obvious.”<\/p><\/blockquote>\n
– Bob<\/p>\n
Bob is an arrogant little prick.<\/p>\n
Here are just a few reasons to document your code.<\/p>\n
- \n
- Other people may need to modify it because, despite your assumed brilliance, there may be other people in the universe capable of maintaining your code when you get a promotion, take another job or get your sorry ass fired.<\/li>\n
- Six months from now, you may need to look at this code again. After 11 other projects have intervened, you’ll be trying to figure out what the hell the prev_grant_yrs variable was supposed to measure. Every time I add comments to a project, I say to myself, “Future me will thank me for this.”<\/li>\n
- If you use Title and Label statements, there will be additional clarity not just for you as a programmer but also for the users.<\/li>\n<\/ol>\n
Here is an example<\/h3>\n
This comes from a longitudinal analysis of a vocational rehabilitation project. There are only two comment statements in this snippet, however, there is a LABEL statement which explains that the prev_grant_yrs variable is the number of years a consumer was served under the previous grant. There was a significant change in operations in the current grant cycle, but when this five-year cycle started there were a number of people already on the caseload who had been determined eligible under the previous administration.
\n
\ndata by_year ;
\nset mydata.vr2018 ;<\/code><\/p>\n** USES YEAR FUNCTION TO GET THE YEAR OF INDIVIDUAL PLAN OF EMPLOYMENT ;<\/code><\/p>\n*** AND OF APPLICATION TO THE PROGRAM ;<\/code><\/p>\n
\nipe_year = year(ipe_date) ;
\napp_year = year(app_date);
\n<\/code><\/p>\nif ipe_year ne . and ipe_year < 2008 then prev_grant_yrs = \"5+\" ;
\nelse if ipe_year < 2012 then prev_grant_yrs = \"2-4\" ; <\/code><\/p>\n\u00a0 else if ipe_year > 2011 then prev_grant_yrs = \"0-1\";<\/code><\/p>\nLABEL prev_grant_yrs = \"Years Under Previous Grant\"
\nipe_year = \"Year IPE written\"<\/code><\/p>\napp_year = \"Year applied\" <\/code><\/p>\n<\/code>;<\/code><\/p>\nThe first procedure, I simply wanted to get a closer look at the people who had been getting services for more than five years under the previous grants. It’s important to add that second title line so readers know this isn’t ALL long-term consumers but those who had been long-term users coming into the current grant cycle.<\/p>\n
TITLE \"Check long-term consumers\";<\/code><\/p>\nTITLE2 \"Getting services 5+ under the previous grant\" ;
\nproc print data= by_year ;
\nwhere prev_grant_yrs = \"+5\";
\nid username ;
\nvar ipe_date app_year prev_grant_yrs ;
\nformat ipe_date mmddyy8. ;
\n<\/code><\/p>\nThe second procedure, I wanted to see how consumers served in the current year were doing. Why do I have grantyear as a variable in the VAR statement when it is clear from the WHERE statement that only people from 2018 will be included?\u00a0 Because the person who gets the output won’t see that WHERE statement. Just having “current year” in the title is not enough because next January someone looking at this might think it was for 2019.\u00a0 I could have included 2018 in the title, but including it as a variable on the output both acts as a validity check for me and lets the user, my customer, know that the data are correct.<\/p>\n
TITLE \"Current year consumers\" ;
\nproc print data=by_year ;
\nwhere grantyear = 2018 ;
\nid username ;
\nvar grantyear status status_type ipe_year;
\nformat ipe_year mmddyy8. ;
\n<\/code><\/p>\nA few of the individuals served by this project did not have an Individual Plan of Employment. I wanted to see if the people missing an IPE just hadn’t had time to complete it yet or if they never came back and did it. An IPE is the first step in getting project services, so, if they had a missing date for a year or more than they had just dropped out. Again, the second title line tells the users what I’m trying to do here.<\/p>\n
TITLE \"IPE YEAR by Application Year\";
\nTITLE2 \"Note: Missing IPE consumers had ample time to complete IPE\";
\nproc freq data=by_year ;
\ntables ipe_year*app_year\/missing ;<\/code><\/p>\nSo, you get the idea. Elegant code is nice, correct code is essential.<\/p>\n
You know what is essential?<\/p>\n
A young person once asked me,<\/p>\n
\n
“No offense, but why are your services so much in demand? It’s not as if there aren’t a lot of people who can do what you do.”<\/h3>\n<\/blockquote>\n
Okay, first tip, young people, when you find yourself saying, “no offense” you should probably just stop talking and then you definitely won’t offend anyone. Actually, I was pretty amused. It’s true that lots of people can do frequency distributions, if-then-else statements and cross-tabulations (although, in my defense, that’s not ALL I did on this project).<\/p>\n
One essential skill is make your analyses easily understood by your co-workers and customers.<\/p>\n
As a wise person once said,<\/p>\n
“Mystery novels should be figured out. Code should be read.”<\/p><\/blockquote>\n
\nWonder what else I’m writing these days?<\/h2>\n
You can get A Different Kind of Textbook, our family group text, for $2.99 as an ebook.<\/a>\u00a0 We definitely are a different kind of family.<\/h3>\n
![\"Contacts](\"http:\/\/www.thejuliagroup.com\/blog\/wp-content\/uploads\/2018\/08\/7-Generation-Games-Text-Book_Page_06-561x1024.jpg\")
<\/a><\/p>\n