Feb. 8, 2008 UHCO Graduate Course in MATLAB Core Programming Module Best Practices Core Grant Programming Module Best Practices (Coding Conventions) General Best Practices MATLAB Best Practices

Feb. 8, 2008 UHCO Graduate Course in MATLAB Acknowledgements Originally compiled by Raja Nadar (an RA from Computer Science) and Hope Queener –Macadamian Technologies Inc., a software engineering and consulting firm based in Ottawa, Canada. –Industrial Strength C++ by Mats Henricson, Erik Nyquist and Ellemtel Utvecklings.

Feb. 8, 2008 UHCO Graduate Course in MATLAB Core Grant Programming Module NIH Funded support for software development for NIH investigators One of 4 Modules –Instrument Design, Biostatistics, Imaging Hope Queener is Principal of Programming Module

Feb. 8, 2008 UHCO Graduate Course in MATLAB Best Practices Conventions for writing software Avoid typical pitfalls Strategies for long-term maintenance Provide consistency for single developer Provide consistency between developers

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Source Code Organization Naming Conventions Programming Conventions Source Code Documentation Error Checking and Debugging

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Source Code Organization Give source code (.m) files meaningful names Add “version” notes to archives of files, not your working copy –work with: StereoStimulus.m –store old versions as: StereoStimulus m –avoid adding words like “final” or “old” to a file name –if using several files, copy all to an archive folder Avoid hard-coded path names in source files –use uiputfile and uigetfile to let the user select the files

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Source Code Organization (continued) Maintain only project source files in the source code folder –Copy old versions of files to archive folders –Maintain extensive data in a separate folder –Maintain separate folders for projects Maintain daily backup development folders –StereoStimulusArchive\ –What did I do yesterday when everything worked? Back up files to another device or backup media

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Naming Conventions Use full, meaningful names for variables and functions For variable names choose adjectives and nouns. –spatialFrequency For variable names and function arguments use “camel” notation For function names, use a strong verb followed by an object. –PrepareStimulus(stimulusParameters) For function or method names, use title (Pascal) case Note that MATLAB help shows a different naming convention, but by using a different one it is easier to distinguish user-defined variables and functions

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Naming Conventions (continued) Use consistent naming patterns for similar operations –Choose one: compute, calculate, or find Include units in variables representing physical quantities (pixels, mm, Hz, ms) Use “temp” in a variable only within short blocks of code Avoid the use of underscores in variable or function names (awkward to type)

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Naming Conventions (continued) Use only well-accepted acronyms or abbreviations and do so sparingly. Avoid arbitrary abbreviations in variable names –Keep all the vowels –The longer name is much easier to understand for the poor soul that inherits your code Use single-character variables sparingly and with clear purpose –use (row, col) rather than (i, j) or (x, y)

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions Avoid hard-coding values –Store fixed values in a variable, and use the variable –Obtain values from the available files and user input, rather than hard-coding Avoid global variables –Global variables are rarely needed and make code harder to maintain and reuse Use loop or index variables consistently in your program (same variable for same purpose) Check all possible conditions in a switch/case statement Declare one variable per line

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions Maintain a consistent layout style. For long expressions, put separate conditions on separate lines –Use MATLAB... syntax to extend a statement to multiple lines Compare numeric values from lowest to highest to mimic math expressions –((0 < col) & (col < widthOfImage)) Indent argument lists for functions that wrap to the next line

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions When you start to copy and paste a block (multiple lines) of code: –Consider redundancy: Am I doing something that could be in a loop? –Consider a new function: Are the two blocks identical except for a few parameters? Aim for source code modules of 1000 lines or less

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Documentation (Comments) Include an introduction comment at the top of the source file: author, date, purpose Include copyright information, if applicable When declaring variables, add comments on the same line Comment on the purpose of a conditional block of code or loop Describe each routine briefly at the top of the routine. Document the source of algorithms that are used Comment on the routine's limitations

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Error Checking/Debugging Check the arguments that come in to a function Use messages to signal code that should never be executed (if/then/else or switch/case) Detect and handle an error that affects the rest of a routine –return status from functions that others depend upon Remember that error handling code is vulnerable to errors Use meaningful, polite and grammatically correct messages

Feb. 8, 2008 UHCO Graduate Course in MATLAB MATLAB Best Practices Source Code Organizaton Use functions rather than scripts Use separate m-files for generic operations Keep specific functions in the same m-file that calls them Add only general toolboxes to the MATLAB path –avoid building up many folders in path

Feb. 8, 2008 UHCO Graduate Course in MATLAB MATLAB Best Practices Naming Conventions Use general conventions, usually When using GUIDE –rename the tag property of each control –retain the automatic function names –use the handles structure carefully

Feb. 8, 2008 UHCO Graduate Course in MATLAB MATLAB Best Practices Programming Conventions Remember that MATLAB was developed to do math –Use vectors and matrices rather than loops –MATLAB examples read like math papers Remember that for-loops in MATLAB differ than for-loops in C –MATLAB loops operate for each item in list –C loops increment a variable

Feb. 8, 2008 UHCO Graduate Course in MATLAB General Best Practices Hope’s Favorites Add “version” notes to archives of files, not your working copy Maintain daily backup development folders Back up to other media Avoid hard-coded path names in source files Avoid hard-coding values Use full, meaningful names for variables and functions Consider before you start to copy and paste a block of code