MATLAB_project_organization_approaches - depcharge-org/depcharge GitHub Wiki

MATLAB project organization approaches

The word "project" is being used here not to refer to "MATLAB Projects", but in the general sense, referring to how a body of MATLAB work is organized with regard to folder structure, version control, MATLAB packges, the MATLAB path, and any dependency support.


A) No organization.

Single folder with m-files. No namespace +package folders, no path management. May use version control.

  • As the main project, this is the naive way of using MATLAB, but it plays to MATLABs strengths, which are minimal setup.

  • As a dependency, it can be challenging because when it is added to the path, all files exist in the global namespace. Collisions are very easy if general names like "radar" or "arrange_figures" are used by functions. Fixing name collisions tend to break version control.

    ├─ .git/
    ├─ main.m
    ├─ function.m

B) Multiple folders added to the path. Package folder unused.

In this approach, package folders are either unused altogether, or have limited use. Significant parts of the code are outside of packages, so must be put on the path in the global namespace.

  • Provides a way to organize files into folders, but doesn't declutter the global namespace, since every folder must still be added to the path.

    • Essentially the same downsides as no organization. Files pollute the global namespace, so compatibility must be assessed for each library and each computer that it will be used with. Similarly, even within the project the namespace can feel crowded.
      However, this is essentially the same organization used by MATLAB for their public facing toolboxes. MATLAB official toolbox functions are not generally behind a namespace, but are accessed directly. MATHWORKS has to deconflict all their own toolbox names, and essentially assume that there won't be any custom toolboxes which have name collisions with names as general as tcpserver tcpclient and quaternion.

    • Adding each folder to the path can feel like extra work that some folks would prefer to avoid, but this is usually automated with a path_setup.m function.

    • An important advantage over MATLAB packages: the folder organization can be changed independently from the code.

├─ .git/
├─ main.m
├─ path_setup.m
├─ visualization/
│  ├─ plot.m
│  ├─ tilefigures.m
├─ math/
│  ├─ add.m
│  ├─ multiply.m

C) One or more packages contain all code, single path root.

  • Advantages
    • Global namespace is kept clean! If package names are unique, the project can be on the path, and you don't have to worry about collision.
    • Namespace is organized! The benefits of folder organization now extend to the MATLAB session auto complete as well. This can make coding easier since the functions are organized
  • Disadvantages
    • In most cases, MATLAB package paths must be used in their entirety to call a function.
      Work arounds exist such as import statements, but unlike in Java in which an import statement's scope covers all functions and classes within a file, the MATLAB import scope convers only the function or script in which it is declared.
    • Consequently, you cannot change the package directory structure without revising the code in all affected function calls.
    • Unlike languages such as Java, the required
    • The entire package path must be used when referencing a function, and there are few exceptions to this. There are exceptions to this, but each has a disadvantage. This is a major disadvantage of MATLAB packages as compared to other programming languages.
      • Package deficiencies
      • package import and : Note that all of these require a definition within each function context that the shortcut is desired in. If you have many small functions, this may not be worth it.
        • Import statement. Needed peer function, and (used to) break find function definition
        • Create alias. Similar to import statement, but you can trace the definition this way.
        • Put static functions in a class. If you make an instance of the class, you can use it to access these member functions without using the entire package path.
    • Deeply nested packages lead to long function calls!
├─ .git/
├─ +project_name/
|  ├─ main.m
│  ├─ +math/
│  │  ├─ add.m
│  │  ├─ multiply.m
│  ├─ +visualization/
│  │  ├─ plot.m
│  │  ├─ tilefigures.m


D and E are more focused on dependency management than general organization

D) Strict form of D, ONE package tree contains all delivered code.

Strictly one package, one path folder.

When multiple repos are combined into a delivery, some would say that these should be combined into a single unifying package, so there is just one folder which must be added to the path, and all utilities are accessible through a single unified namespace.

  • Advantages
  • Disadvantages

E) DepCharge mix of top level package and path automation

⚠️ ** Fallback** ⚠️