MathGroup Archive 1995

[Date Index] [Thread Index] [Author Index]

Search the Archive

Re: Crossreference, code documentation

  • To: mathgroup at
  • Subject: [mg1610] Re: Crossreference, code documentation
  • From: <larso171 at>
  • Date: Tue, 4 Jul 1995 03:18:37 -0400
  • Organization: University of Minnesota, Twin Cities

Hi all,

I'm the one who wrote the message regarding a tool to build a function - 
variable cross reference table:

 function      variable            global   global
 name          name       local?   used?    modified? 
 =========     ========   ======   =======  ==========
 func1         xabcF1      Y         N          N
 func1         xdefF1G     N         Y          N
 func1         xghiF1G     N         Y          Y
 func2         x123F2      Y         N          N
 func2         x456F2G     N         Y          N
 func2         x789F2G     N         Y          Y
 func2         xjklF2      Y         N          N

While I was thinking about it some more, a much more urgent need is a tool 
that compares global variable names to a list of "correct" variable names.  
E.g. given a list of correct global variable names, I'd like to know about 
any global variables in my code that do not match any of the correct 
variable names.  This would be useful with local variable names too -- 
particularly in implementing a consistent or new naming convention as 
described below.

Then, additionally, there should be find and replace capability.  i.e. 
given the information above, I'd (probably manually) create a list of old 
variable name and new variable names:

    old name    new name
    --------    --------
    flixlz      flixGL
    mutparm     mutateParmG

The need arises because while developing my application, and as it grew 
in size and complexity, I decided on some various naming conventions in 
midstream.  So some functions, written earlier, have variable names that 
conform to an older variable naming convention (or no convention at all).  
I'd like to get it all up to snuff.

Finally, I'd like, when I'm done with version 1, to think about a different 
better naming convention.  IMHO, consistent, descriptive (but not overly 
long!) variable names make a large program much more understandable.

Some might say "why didn't you think about a good naming convention before 
you started?"  The answer -- I did.  But as I wrote code, I came up with 
additional better ideas for naming variables clearly and consistently.

I'm certainly open to other ways of doing this than MMA code, e.g. using 
Word 6 or Excel 5.  But these don't seem to have much capability for 
identifying inconsistent variable names, or replacing one list of variable 
names with another.

It seems fairly easy to do -- write MMA code to do these two functions:

(1) unMatchedList = findUnMatching[correctList_, sourceCodefileName_]

identify variable names that don't match a "correct" list of variable 
names, and 

(2) newSourceCode = 
     replaceVarbNames[oldList_, newList_, oldSourceCodeFileName_]

i.e. given an old variable name list and a new variable name list, replace 
all old variable names by the new variable names.

Its my experience though that what looks simple on the surface often is 
bedeviled by details.  Such a program would need to 

  (1) identify  names (I don't need to distinguish between function names 
and variable names I don't think -- I'd like to do function names too the 
same way), and not get messed up by special symbols like "[", "(" etc.
  (2) ignore any "names" in comments, i.e. ignore comments entirely (I've 
already done this part with my comment remover program).  Trouble is... 
though stripping comments out makes writing the cross reference program 
and the findUnMatching[] programs easier to write, it doesn't help with 
the replaceVarbNames[] function, because I want to replace variable names 
in the source file that includes the comments.  OTOH, I can live with, and 
probably prefer that it replace old name with new name in comments as 
well, so probably no need to distinguish comments from real code
 (3) identify whole words only, i.e. I don't ever want the variable "mut" 
to match the variable "newmut" or "mut1"  (Now you know why wholesale 
replacing of variable names might be a good idea for me).

It still doesn't look  too hard, but considering how much time my "comment 
stripper" program took, it is wise for me to ask around if something 
already exists to do this.  Or if a devastating "oneliner" solution pops 
up in someone's mind.  Usually the best one liner solutions that I come up 
with look like:

    For[i=1, i<=Length[list], i++, (* decide what to do *) ]

Thanks all for reading these long messages.  If something doesn't turn up, 
I'd be happy to share what I develop -- inelegant but does the job.  Or, 
better yet, to pool development effort.  e.g. the comment stripper 
program I wrote would be better if:
  (1) More elegant -- I know there must be a way to replace my horribly 
long procedural code
  (2) It still occasionally leaves a blank line when a comment is removed 
-- I haven't tracked down why.  
  (3) Have the option to leave "end of line" comments in, as these are 
often very informative without increasing the program's length in number 
of physical lines. 
  (4) Have the option to leave one or two line comments in, but remove all 
the lengthy dissertation - style comments that I tend to write.
  (5) Treat special kinds of comments differently.  For example to "comment 
out" a line of code, I have the convention of using the comment delimiter 
(*| ... *) as in:
    (*| perhapsTemporarilyCommentedOutFunction[]; *)
And things that I'm especially worried about I indicate with (*! ... *)
such as:
    (*!  below changed 6/29 but not tested -- will it work with lists? *)

Enuf, Bye, and Thanks

Jim Larson

  • Prev by Date: Fourier Question
  • Next by Date: How to draw OUTLINES on 3D shapes?
  • Previous by thread: Re: Fourier Question
  • Next by thread: Crossreference, code documentation