08-04-2015 03:28 PM
I'm looking into creating an automatically generated header for new programs that does not involve copy-and-pasting a header from another file.
* Name of Program:
* Date created:
* Date last modified:
* File path to program:
Several of these values could be inserted using a macro variable that is created by the system, but I would like the header
08-05-2015 04:45 AM
I have also a standart header. To avoid to type it every time I have a abbreviation. Yoy could se how to do it in this paper http://www.pharmasug.org/proceedings/2015/QT/PharmaSUG-2015-QT26.pdf
08-05-2015 05:09 AM
Can I make a suggestion here. It seems like some sort of historical thing this whole "header" for a program. I notice it in virtually all SAS environments, and frankly its ridiculous. In this day and age manually updating text to say when things were last changed and what has been changed etc. For decades now there have been version control systems whose whole purpose is to track changes within source code files - automatically, i.e. no human mess ups - and they are far better at it. The other thing I notice about these "header" bits is that there never seems to be any solid software development cycle behind it. Lets pull apart that header block:
Name of Program:
- So what do we mean by Name? Is it the filename, if so why bother repeating it here. How is this referenced to the functional design specifications (or specifications). Ultimately is this adding any new information?
- Well, the Owner is the company you work for, they hold IP on anything done at work, so this becomes irrelevant. If its the developer, then it should refer to the developer group rather than one individual. Individual developer would be defined in the overall tracking of programs/macros.
This adds no value. It is a totally manual thing and open to abuse just like file creation dates and such like. A version control system would have the date of first commital - i.e. the first moment the file is submitted to versioning, this would be the first active date of the program, be it test or production.
Date last modified:
Whilst good in theory, does everyone update this everytime there is a change. So often you see programs with last changed on date way out from changes. This goes for the other good old favourite, the change history section. Have a look through some programs which have change history, its amusing sometimes how wildly different from the programs they are. Comments in the program as well, when you make a change do you actually look at all comments and references to ensure they match up? Now version control software will do all of this for you. Make your changes and commit the file and you have an unchangeable record of when the file was committed, who committed, and a record of exactly what text in the file was changed. Full audit accountability, with the option of adding further information such as reasoning, bug logging into the commit.
File path to program:
In this day and age we should not be thinking in terms of fixed pathing structures. I am not sure what industry you work in, however in my field we have thrid party vendors providing us code, and we have to ship code off to regulators etc. Everybody and his dog has their own file structure setup. This should however not prevent our code from a) running, b) being documented correctly. To this end we should be focused on a virtual file structure. Many methods of this, a simple way is to fix a root folder, and then have a fixed structure from the root down, so the root folder can be picked up and placed anywhere as long as all folders below remain unchanged.
This one I don't mind. It can actually add value to a program, being able to get an overview of what the program is generally supposed to do without opening other documents. Include as you want.
So the TL;DR version of this is to use automated tools to deal with version control/audit history - don't manually do this which is fallible. And also think of the bigger picture in terms of running code on platforms other than your own, and involve processes such as SDLC which regulate the programming in a standard and consistent way.
08-05-2015 07:00 AM
Well, i do like to have some information that is not covered by the VCS in the SAS code like
- who ordered the program originally (dept., name)
- which files are required, which files are created
and I do keep a short (one-line) version of the change history in the code. Just to know at one glance if a recent change could be the culprit.
Although this information is stored in the documentation database (and no program can be committed without that), I like to have some information included in the code (and therefore in the log), because I may have trouble accessing the doc database from a remote location while being perfectly able to read the log (of a crashed run) with a simple ssh to the BI server. Or the doc database (or the VCS) may be down for maintenance while I'm trying to solve a problem.
08-05-2015 08:30 AM
Ok, yes I can agree with you on your first points Dependencies is an area in SAS which doesn't self document well. However saying that the FDS or other documentation should indicate the dependencies as a visual graph - depending on the complexity.
On the second point, I wouldn't keep that information as text in the file then. I would have a small macro call at the beginning of the code which calls the changelog from VCS, in much the same as I would have this when the program is run, so that full history is available in the log at runtime. Then it would be a matter of highlight and run the macro to get version history. I doesn't matter too much, but I have had several instance where code actually gets findings returned due to comments or headers not matching, I just find it simpler to let software handle that although you would need a policy on what is entered into the CVS at each commit.
Admittedly, I am talking about an ideal world, and there are always limitations like maintenance.
08-06-2015 01:09 PM
While I appreciate your feedback on the discussion of headers, it did nothing for my problem. Where I work, maintaining a clean introduction to code and being able to reference is very important, as everything is stored on a server. Also, those fields were just to populate a potential header, not that they would all be implemented.
08-06-2015 02:16 PM
You may want to consider using a different editor. There are some programming editors that have the ability to have information such as created, last saved and location information that updates.
I did something similar in the days of SAS 6.8 to use an editor that had more features than the SAS editor.
08-07-2015 03:53 AM
This is pretty much exactly as everyone else works, be it in SAS or other languages. You should still have in place a version control system, and as you have automated software to control versioning, commits etc. then why not use that functionality. Both of your points - "clean introduction" and "able to reference" would both be handled fine by a VCS, and by not doing this manually you stop the "human error" problems which always creep in when its manual.