Date:         Mon, 22 Mar 2004 17:14:46 -0500
Reply-To:     "Fehd, Ronald J. (PHPPO)" <rjf2@CDC.GOV>
Sender:       "SAS(r) Discussion" <SAS-L@LISTSERV.UGA.EDU>
From:         "Fehd, Ronald J. (PHPPO)" <rjf2@CDC.GOV>
Subject:      Naming Conventions was: multiple condtional macro calls in one
              statement
Content-Type: text/plain; charset="us-ascii"

long: six screens
> From: Fehd, Ronald J. (PHPPO) [mailto:rjf2@cdc.gov]
> To: An Enquiring Reader
> Subject: RE: Re: multiple condtional macro calls in one statement
>
> > I find the more I read yours and Ian's reply's, I have much
> > to learn in the way of thinking and writing skills.  Perhaps
> > that is why you two write books and papers and are always
> > asked to give talks.  I would definitely agree with your
> > naming convention but would add something about the
>
> > abbreviating words
>
> uh, I'm unclear as to what you mean by that,
> expand that, so I can anchor it to what I wrote.
>
> > (if my understanding is right there is a
> > right and wrong way to do it).
>
> sorry to say, there is no -- Generally Agreed Upon --
> right and wrong way to do this.
>
> Due to lack of understanding on everyone else's part? ...

and the requested reframe was:

> I referring to naming conventions whether for a routine,
> sub-routine, module, macro, etc... As you stated a good
> naming convention will convey not only what the routine (for
> example) is doing but what it is doing it to.

right, input, process, and output
should be obvious from the routine name and parameter names
Is there more to know than that?

> However, it is my understanding that it gets cumbersome
> sometimes when a name gets to long to write out in long form.
>  Getdata is good because it is short and descriptive, however
> ( I would note that it does lack some clarity as to what it
> is getting data for).  Now let's say we wanted to create
> counts of different color m&m's.  Here it would be hard and
> cumbersome to have a name like countsdifferentcolorM&MS, so
> one could shorten it such as cntdifcolmm  which while lacking
> the true readability of the afore mentioned name does a
> pretty good job of getting across what the function or
> routine is for and substantially shortens the name.

routines, or sub-routines, are implemented in SAS
as either of %includes, very simple, with lack of easy control structure
or macros, with automagic, whizardry etc,

wrt macros, macros can be within a program
in which the Gentle Reader is referred to the definition
further up the page, there positional parameters are de ringeur,

when macros are stored outside of the program they are used in
they are available to other programs, jobs, modules,
and are quote: reuseable.
then we foresake positional parameter
except in the most obvious cases,
where the routine name is what I call a Strong Verb
i.e, a much-used SAS native function or procedure name,
like e.g. Xor or Freq1Var

in order to facilitate reuse by other than the maverick that wrote them
a good set of naming conventions ought to be agreed upon
both for the routine/macro name
and the common parameters

parameters:
well the three main ones are:
Library = Library, incidentally where the default
                   format catalogs are also stored
Data    = Data
Var     = Var

to facilitate the fairly obvious usage

PROC MainVerb data = &Library..&Data.
              <Var>    &Var.;

How many ways can one spell Library?

LibIn
Lib_In
MyLib
TheLib
Storage
LibSpec

How many ways can one spell Data?
Data_Set, which I use in the global mvar list
DS
DSN
MyData
YourData
OurData
TheData
A_DataSet_Name

How many ways can one spell Var?

Column
Col
TablesVar
ClassVar
CharVar
NumVar
Var4Table
VarC
VarN

Naming Conventions reduce emphasis on trivia.

You'll (have hopefully) noticed the one-to-one correspondence
between my macro calls and my procedure templates:

PROC MainVerb data = &Library..&Data.
              <Var>    &Var.;

%MainVerb(    Library = Work
             ,data    = DataA
             ,Var     = VarA
             );

example: I posted a macro PUT_
what do you already know about about the SAS statement:
%Put note to log?;

its parameter is a text string
and one can insert macro function calls
like sysfunc(getoption, and sysget

so how obtuse is the call:
%PUT_(list = SysDate SysTime
     ,type = mvar
     );
or
%PUT_(list = leftmargin rightmargin topmargin bottommargin
     ,type = option
     );
or
%PUT_(list = altcfg
     ,type = constant
     );

%PUT_(note = list of parameters local to this routine
     ,type = text
     );

I have received critique saying that my parameter named list
might better be named var:

%PUT_(var  = leftmargin rightmargin topmargin bottommargin
     ,type = option
     );
or
%PUT_(optionvar  = leftmargin rightmargin topmargin bottommargin
     );
%PUT_(mvar = SysDate SysTime
     );
%PUT_(constant = altcfg
     );

what's to figure out?

is it 5:?? yet?
Monday Musings will be continued
   tomorrow
or next week

Ron Fehd  the macro maven  CDC Atlanta GA USA RJF2@cdc.gov
keyword: theory