How to visualize the project structure in MATLAB?

Question

I became the owner of several thousand lines of Matlab code, some of them → 900 line functions and several directories filled with function_name.m files. It is difficult to understand what everything does (or relates) or finds out the dependencies. What would you suggest to visualize the structure of functions, for example, which functions are called and from which sequence?

Answer 1

Port in NumPy.

(Joke.)

Usually in Matlab you have files written as functions, and some as scripts. Scripts perform functions such as loading the data you want to process, and feed them into functions, and draw them.

To organize things that I would start at the top level of the script and find out what functions load, graphic design, processing, etc. Store the scripts in a top-level directory and try to separate these functions from subdirectories, according to the purpose of the function. Place the function dependencies in the same subdirectory. Try to make sure that no code in the directory depends on anything in the parent directory (or cousin's directory).

Whenever you figure out what a function does and what its arguments are, write a comment on the document.

This suggests that the person who wrote the code was reasonable. If not, Matlab makes it easy to put everything in one directory and it all depends on everything else in the shaky tower of code, so you can end up doing a lot of refactoring.

Answer 2

Does your code have suitable help text? In this case, m2html will be a big help, as it allows you to create related html help for easy viewing.

In addition, it allows you to create dependency graphs that will help you understand a little more how you can organize your code.

Answer 3

I have had to deal with this issue many times in my various roles in The MathWorks. This is what I do for large MATLAB code snippets:

• Make a backup, maybe twice!
• Select All, Ctrl-I for Smart Indent

• Select all, Ctrl-J to wrap comments

• If I feel the paper - print all the files and get a set of markers - follow manually, highlighting long-term variables and important function calls.

~~~ AND / OR ~~~

5 If I’m lucky, run the code in the debugger by going through one line at a time (entering into subfunctions that were written by the user)

At this point, I can go through and follow a typical flow through the management structure. I may not have a great idea that everything does, but I have a decent idea of ​​what's going on.

Usually my goal is to find a mistake, solve it and continue. Your goals can be completely different. This is the method that I used to quickly comprehend the crunching of different parts of the MATLAB code that I sent over the years.

Answer 4

Richard Johnson's MATLAB Programming Style Guide is a good resource.

Answer 5

Some suggestions regarding the Matlab coding convention:

• use addpath to prevent clutter of files and help with taxnomony functions

• Split partition_ for functional scripts or set for conditional runs, this can also help with plug-in / out and reuse or code references.

• use the configuration file to turn parameters on and off

• have a general overview of the architectural set of designs, as well as modus operandi
• save the status / readme file (consider yourself as a new user, how would you help make it assimilable as part of your own module or part of solutions for a new user, if you return to code 3 after a few months feeling lost or unable to trace - something is not so.) My suggestion: keep a journal to clarify your thoughts on preserving skillful projects. Keep improving your art!
• for equations, use latex for documentation (and store it in the nearest folder under the name, for example, documents, make sure they are easily accessible and traceable - if you need to use the “search” on your disk, something is wrong with project management)
• break codes into short modules for localization and shorter codes, with less scrolling, codes will be easier to track.
• use meaningful variables and function names (the java style seems nice, for example, "backedupDataForVerification"), do not limit, to shorten the words, you will suffer later
• When designing, consider whether to use a function, scripting, or OO (object oriented)
• Do not rush to premature optimization, as Matlab speed is not the best choice. If you really need to, do not save a single optimized version for side-to-side matching; troubleshooting and debugging will not be less than a curse.
• Always, always, always comment on your codes. Never use the excuse that you do not have time, you will lose more time.

• for differentiation, consider installing a new node to modify the code, for example. set tree to distinguish between versions.

• use a separate folder for inputs / outputs, images, intermediate results, etc.

• use timestamp for version tracking

• share your codes with someone else if it is difficult for them to maintain, use or modify, rethink how to refine your builds.

Answer 6

Back everything is correct. Create an initial tarball of the source source tree, and then drop it all into the source control so you can track and roll back your changes.

Take a look at Matlab depfun () and depdir (), which detect static dependencies. This can help you see the dependencies between Matlab features. With "depfun -toponly" in all files and a little line shuffling, you can create a list of immediate dependencies and drop it in the GraphViz file to create a large oriented graph of your code connections. Clusters on a graph can be a good place to split code. (EDIT: see Jonas solution, it looks like m2html does this for you.)

If you have more freedom to rewrite code, consider rewriting part of the code as objects using stateless utility classes with class methods and private functions as ways to combine related functions and provide some encapsulation. I worked with the fairly large Matlab codebases organized in this way, and everything works. In classic Matlab, classes are your only way to make some kind of packages. I believe the new OO Matlab system also supports a namespace.

If you do not want to convert the code to OO, you can organize related functions in subdirectories. This helps organize it to view the source code, at least.

All functions must have some doco in the standard hellext Matlab format, including the H1 line. If they do not, write comments about what you learned there. Then use the "contentrpt" tool to automatically create table of contents files for classes or directories.

Good luck.

Answer 7

I agree with most of the comments that Matlab does not terribly support the modern structure of software source code, but I do not find it too difficult to impose some of your own structures with a little discipline.

Organize the source files into a directory hierarchy, just like the source files for any program written in another programming language. You do not need to adhere to a hierarchy; if you want, select your structure. Use the setpath command (or whatever it is) to tell Matlab where to look for your m files when you work.

Get yourself with the Matlab profiling tool, which can give you call diagrams (rather than terribly graphical, more like gprof call graphs), which is some help in deciphering spaghetti code.

Of course, all of our m files are in the repository, and we serve them. We keep private toolkit on one of our network drives, and all users can directly call the "released" code in this toolbox.