Re: Crossreference, code documentation
- To: mathgroup at christensen.cybernetics.net
- Subject: [mg1610] Re: Crossreference, code documentation
- From: <larso171 at maroon.tc.umn.edu>
- Date: Tue, 4 Jul 1995 03:18:37 -0400
- Organization: University of Minnesota, Twin Cities
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
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
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
(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 (*! ... *)
(*! below changed 6/29 but not tested -- will it work with lists? *)
Enuf, Bye, and Thanks
Prev by Date:
Next by Date:
How to draw OUTLINES on 3D shapes?
Previous by thread:
Re: Fourier Question
Next by thread:
Crossreference, code documentation