macro parameter naming convention

[xxformat_com]

Hi,

Do you apply a naming convention for macro parameter names, names which are meaningful for the end user?

What name would you use in the following circumstances:

A: C:/mydir/mysubdir/helloworld.xlsx

B: C:/mydir/mysubdir

C: C:/mydir/mysubdir/

D  C:/mydir/mysubdir/helloworld

E: helloworld

F: hellowworld.xlsx

G: .xlsx

H: xlsx

Question inspired from: https://stackoverflow.com/questions/2235173/what-is-the-naming-standard-for-path-components

[yabwon]

First remark and my personal preference, but also _not_ my programming practice: as long as you _document_ what the parameter is - name it as you want. 

Second remark:, I would consider the following names:

A - pathToFile or filePath

B,C,D - path, or maybe rootPath

E - is it a file or directory? if first then fileName if the second dirName

F - fileName

G,H - ext or extension

But as I wrote "document the meaning in the first place".

Bart

[xxformat_com]

E is the file name without the extension.

[yabwon]

One more remark, this thread seems to be "touching" dangerous area of "religion of SAS" 😄

@Quentin @FriedEgg 😄

Bart

[Kurt_Bremser]

Whatever floats your boat. With files, the name must convey its function (in, out, update). Document if the complete path or just the filename is needed.

[ballardw]

Only two of those values are valid for Macro variable names so most of that is not usable as "parameter".

You cannot have .  / :  in macro parameters (variable names) only letters, the underscore and digit characters are allowed and must start with letter or underscore.

Names of variables often have something to do with the role the parameter will play: filein for example for some sort of input file, fileout for an output file, msgtext for a parameter to hold some random text values for display. With that sort of thinking I don't really see any that come close especially without knowing exactly what said "macro" is supposed to do.

[xxformat_com]

The values I've given in the question are for the macro parameter VALUES. I've not given any macro parameter name in the question. I was asking for suggestions for macro parameter names when the expected macro parameter values are as given in A... G

[Tom]

As others have noted you have conflated two topics here.

One is the topic from your linked post, how to name the various components of a filename.

The other is what are useful patterns for naming variables (whether normal dataset variable, or normal macro variables or macro variables used as macro parameters).

For the later you should include the role that the value is being used for.  So perhaps an INFILE or OUTFILE.

Personally I use directory instead of "folder".  I haven't used manila folders in a long time. In fact I don't even have any desk drawers or file cabinets in my office where I could store a folder.

The extension (or ext) on a file is the part after the last period.  If there is no period then the extension is blank.

if index(file,'.') then ext=scan(file,-1,'.');

Being too picky about whether to use a different name for a filename without a directory verses a filename with a directory included is probably not important in most uses.  Your macro should be able to adopt to either.  

And if the macro requires that the user pass in the directory name and name of the file within the directory separately then it should be pretty clear to the user that whatever name you used for the two parameters that they will be combined to make the full name.  And again you can make the macro smart enough to handle what you are passed.  For example you could append a / to the end of a directory if there is not one there already.

%if %length(&dir) %then %if not %index(/\,%qsubstr(&dir,%length(&dir)))
  %then %let dir=&dir/ ;

[Astounding]

Computers don't care what you name your variables.  You could name them &abdomen and &zebra for all a computer could "care".  The purpose of your question is to make your program more readable and easier to use for the next human that comes along.  Toward that end, here are some conventions I follow.

Every macro begins with a %global and a %local statement along these lines:

%global gname1  /* description of the purpose of &gname1    */
        gname2  /* description of the purpose of &gname2    */
        ;

The comments are usually one line long for each macro variable, but can be longer if needed.  And when using a monospace type, the asterisks line up so the reader can easily see the location of all the comments.

The names themselves are intended to make the purpose clear to a human.  For example, these are vague names:

file
vars

These are better names:

n_vars
incoming_varlist 
numeric_varlist
output_filetype

They take a little more typing, but they help the user understand the code as s/he looks through it, and lessen the need for the user to refer back to the comment sections when reading through the code.

Just my opinion, FWIW.  Readability is in the eye of the beholder.

[Quentin]

This is an interesting question, especially with the focus on the macro user:

---

Do you apply a naming convention for macro parameter names, names which are meaningful for the end user?

On the one hand, as a macro developer, I think this is an important question, and one we should all consider.

On the other hand, as a SAS user, I feel like finding the best answer and using it consistently doesn't matter that much.  Even if you are developing something like a corporate macro library, where one might think that consistency in macro parameter names might be very important and helpful, the truth in SAS programming is that you end up using macros from a variety of sources, that all have different naming styles.  So as macro user, you are used to having to look at macro code to figure out the parameters etc. 

That said, I do think there is value in using consistent names, partly as help to the user, and partly as help to the developer.

I often have a macro parameter PATH, for:

B: C:/mydir/mysubdir

C: C:/mydir/mysubdir/

I'm inconsistent about whether or not the value passed to PATH should end with a trailing /.  Generally I think it "should".  But in the macro code, I don't really like the look of:

&path&file

I just like the look of:

&path/&file

I think Windows and Linux may not care about //, even if it looks weird.  As Tom said, the best answer for path is to allow the user to pass a value with our without trailing /, and have the macro accommodate it.

I also often have a parameter named FILE for:

A: C:/mydir/mysubdir/helloworld.xlsx

hiworld (this is a fileref, not the name of a file without an extension)

F: hellowworld.xlsx

Usually the value to be passed for FILE is either a full path to a file, or a fileref (the user can choose).   It's rare that I would pass just a file name (helloworld.xlsx).  But if a macro has a PATH parameter, then it's possible that a FILE parameter would be just a file name, because the user has already specified the path to the file.  It doesn't bother me that a FILE parameter could be the full path to the file, just the filename, or a fileref.

On occasion I have a parameter EXT or EXTENSION:

H: xlsx

There were probably times when I would ask a user to include a dot in the extension, but to my mind the dot is not part on an extension.  But like trailing / issue for path, for a user-friendly macro it's trivial to detect whether the user has provided a leading dot or not, and handle it accordingly.  So you don't need different parameter names for EXTwithDot EXTwithoutDot.

I don't think I've ever written a macro parameter that asked a user to provide a value for a file name without an extension:

D C:/mydir/mysubdir/helloworld

E: helloworld

Just looking at those, the first value looks like a path, and the second looks like a directory or subdirectory to me, these values don't look like files.

So if I were to pick a standard I use inconsistently, it would be FILE, PATH, and EXT.    But if you looked at macros I've developed, you'd find plenty of FILENAME, INFILE, DIR, FOLDER, etc. 

As IDE's get smarter, they make some of this easier for the user.  For example in EG, if you define a macro like:

%macro foo(
  path= /*path to file, with trailing / */
 ,file= /*file name in quotes with extension or fileref*/
);
  %* ... ;
%mend foo;

When  a user invokes the macro, some of those tips will be available.  It's not perfect, but it's something.  I don't know if there is something like that in Studio, or the VS code extension, but would hope so.