The Blab guide for writing new MATLAB scripts and functions

Last updated 2019-01-15 by Adam Lu

Preparation

Before you starting coding, read the MATLAB Style Guidelines (this is also downloaded on fishfish in /media/adamX/Settings_Matlab/Tutorials).
On the server, create a directory under /home/Matlab called <your-name>s_Functions. Place your custom functions in this directory.
Download and set up Sublime Text via these instructions. Some advantages of Sublime Text over the built-in MATLAB editor:
- Lightweight and fast: In contrast, the MATLAB editor automatically scans for syntax errors everytime you edit the file, a property that is useful when the code is finalized and ready for testing, but creates unnecessary time-lags when the code is still under development.
- Buffered: One can open and save files from the server directly. The code is buffered on the local machine, which increases performance especially when you are working remotely and the internet is slow.
- Environments can be saved: One can edit many files all at once easily by adding folders to projects. The next time you open the project, the files that you were editing last will be automatically opened. Therefore, if you have multiple projects, you can save multiple coding environments. In contrast, the MATLAB editor can save only one such environment.
- Better keyboard shortcuts: The more commonly used settings (CTRL + C for copy, CTRL + V for paste) are used. There is also CTRL + H for find and replace and CTRL + G for navigating to a particular line which can be very handy.
- Highlighted keyword: I like to have the keyword TODO and Notes highlighted, but one can edit the preference settings for the HighlightWord package after setting it up via the instructions here.
- Export as HTML: There is also an ExportHtml package that one can install via the instructions here.

Documentation

When creating a new MATLAB function (not so important for scripts), make sure there is an associated documentation with the following components:
- A single-line description of what the function does: This will show up when others apply the lookfor command.
- Documentation on usage: In MATLAB, the first block of comments will show up when one types the command:
```
help function.m
```
  The documentation should at least include what arguments are needed and what outputs are produced.
- Documentation on file dependencies: What other functions does the function use? What other functions uses this function? This information will be important when you change the usage of a function (e.g., change argument or output order, etc.) and need to update dependent functions in the future. It will also be important when you need to compile the functions into a standalone program.
- A file history: This is how other people who use your code will know if you changed anything to the code since they last used it. It will also help you keep track of any failed attempts you have made in coding.

Tips

Use varargin and inputParser whenever you have optional arguments. This will allow your function to be used in many different ways without the need for keeping track of argument ordering. it will also allow you to prevent a function from taking in a wrong argument type and facilitate the debugging process.

Templates

To facilitate the above two points, you can open the file /media/adamX/Settings_Matlab/function_template.m then save as a new function file under your function directory (i.e., /home/Matlab/<your-name>s_Functions) and edit the contents accordingly. It’s much easier to delete the parts you don’t need than to construct commonly used documentation/code from scratch.

Testing your code

After you have a draft version of a script/function, you can test it out by the following steps:
- Open MATLAB, using either the GUI or the no display version, through X2Go or MobaXTerm via these instructions.
- Either navigate to the directory containing the script/function or add that directory to your search path via these instructions.
- Type in the script/function name to execute and test it. One can easily recall recent commands by pressing the Up arrow.
- Tips for debugging:
  - Apply the command dbstop if error before you run. This will allow you to investigate the state of the variables right before the code errored. Apply the command dbclear if error to reverse this.
  - Apply the command dbstop function.m <line number> or open the code in the MATLAB editor (open function.m) place a red mark before the line of code you want to stop execution at. This will allow you to investigate the state of the variables right before the execution of a particular line. Apply the command dbclear function.m to reverse this.
  - Apply the command dbstep to execute the following line, dbcont to execute until the next breakpoint and dbquit to exit the debugger.
  - In the MATLAB editor, one can select lines of code and execute just the selected lines by pressing F9.