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
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