File Exchange Submission Guidelines
Authored by the MATLAB and Simulink user community on the MATLAB Wiki.
| Table of contents |
Code
The code of the submission fulfills the following criteria:
- It must run without errors.
- It must not require root administrative privileges to install or use.
- Any changes to a user's runtime setting, such as paths, system preferences, warning options, etc., should be restored to their previous states (exception: code with the explicit purpose of making said changes under user control).
- It must be written as a M-function/M-functions (exception: accompanying test and demo scripts may be scripts).
- It must follow these common programming guidelines:
- error handling with intelligible feedback,
- vectorization and other strategies for fast computations,
- proper clean-up, e.g., closing file handles and removing temporary files,
- avoiding eval (and its variants) whenever possible; any usage must be commented and explained within the function.
- comments that clarify the algorithm.
Format
The format of the submission fulfills the following criteria:
- The help section and comments must be error-free.
- The File Exchange metadata must be accurate. Where applicable, a screenshot should be provided.
Contents
To be of interest to the users of MATLAB the submission should meet one of the following criteria:
- Functionality: it offers a function or suite of functions potentially useful to many people.
- Enhancement: it provides recognizable enhanced functionality over what currently exists in Matlab.
- Design: it shows an efficient and elegant way to solve a specific problem.
Directory Structure
For a submission to be considered for File Exchange Select, it should have the following directory structure, though some of the elements listed below are optional.
/ (main directory) Contents.m (directory contents file, if more than one file is present) demo/ (demo subdirectory) demo/html (html subdirectory for any published M-file demos) doc/ (documentation subdirectory, optional) test/ (demo subdirectory) test/test_main.m (test kickoff file)
Here is a description of each subdirectory.
demo
Published M-files (http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_env/noteboo2.html) are recommended for demonstrating code, as these can be previewed on the File Exchange before the download takes place. Published M-files must be MATLAB scripts, but the scripts can demonstrate the behavior of the various functions in the submission.
doc (optional)
The doc directory contains documentation that is distinct from the help that is provided as part of the M-files, although it might be derived from it. We have no standard for this yet. One promising approach is to use an automatic doc generator (like Guillaume Flandin's M2HTML) to produce HTML documentation from the M-files.
test
This subdirectory is required for all submissions and should contain an m-file called test_main.m. The minimum test permitted would exercise as much code of the submission as possible and exit without error (use the Profiler to check code coverage). More elaborate tests, including negative testing, are welcome but not required.
Example
This page shows the abstract description of the files in a submission. For a concrete example, see the Multiplication Toolbox.