1. Feb. 9, 2010 UHCO Graduate Course in MATLAB Core Programming Module Best Practices Core Grant Programming Module Best Practices (Coding Conventions) General Best Practices MATLAB Best Practices

2. Feb. 9, 2010 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.

3. Feb. 9, 2010 UHCO Graduate Course in MATLAB Core Grant Programming Module Programming Module of the NIH Core Center Grant: P30 EY007551 Core Center Grants provide infrastructure support for research centers that include NIH funded investigators One of 4 Modules –Instrument Design, Biostatistics, Imaging, Programming Hope Queener is Principal of Programming Module

4. Feb. 9, 2010 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

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

6. Feb. 9, 2010 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: StereoStimulus20080207.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

7. Feb. 9, 2010 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\20100209 –What did I do yesterday when everything worked? Back up files to another device or backup media

8. Feb. 9, 2010 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

9. Feb. 9, 2010 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)

10. Feb. 9, 2010 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)

11. Feb. 9, 2010 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions Avoid hard-coding values –Store fixed values in a variable, and use the variable trialCount = 10; …(other initialization code)… for trial = 1:trialCount …rather than for trial = 1:10 –Obtain values from the available files and user input, rather than hard-coding reply = inputdlg(‘Enter the number of trials’); if isempty(reply), return; else trialCount = str2num(char(reply{1})) end

12. Feb. 9, 2010 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions (continued) Avoid global variables –The global keyword should be avoided –Global variables are rarely needed and make code harder to maintain and reuse Declare one variable per line Use loop or index variables consistently in your program (same variable for same purpose)

13. Feb. 9, 2010 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions (continued) Handle all possible conditions in a conditional statement if exist('fittype') % curve-fitting toolbox [threshold, goodnessOfFit] = FitWithCurveFittingToolbox(stimulusLevels, percentCorrect); elseif exist('lsqcurvefit');% optimization [threshold, goodnessOfFit] = FitWithOptimizationToolbox(stimulusLevels, percentCorrect); else msgbox('No suitable fitting toolbox available'); threshold = 0; goodnessOfFit = 0; end –“switch, case, otherwise, end”

14. Feb. 9, 2010 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions (continued) Handle all possible conditions in a conditional statement switch (customerRanking) case {'1'} TransferToSeniorCustomerRepresentative(customerRanking) case {'2'} TransferToMidlevelCustomerRepresentative case {'3'} TransferToEntryLevelCustomerRepresentative case {'4', '5'} % service was satisfactory ReturnToMainPhoneMenu return ; otherwise RecordConfusedCustomerRanking(customerRanking) TransferToSeniorCustomerRepresentative(customerRanking) end

15. Feb. 9, 2010 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions (continued) 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 < column) & (column < imageWidth)) Indent argument lists for functions that wrap to the next line

16. Feb. 9, 2010 UHCO Graduate Course in MATLAB General Best Practices Programming Conventions (continued) 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 less than 1000 lines (less is better)

17. Feb. 9, 2010 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 If variable names and functions are self- describing, commenting can be minimal –Comment on the purpose of a conditional block of code or a loop, if not obvious –Use brief comments at the start of a function. –Comment on the function’s limitations Document the source of algorithms that are used

18. Feb. 9, 2010 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

19. Feb. 9, 2010 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

20. Feb. 9, 2010 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

21. Feb. 9, 2010 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 “for” loops: MATLAB & C/C++ –C loops increment a variable –MATLAB loops operate for each item in list “switch/case” loops: MATLAB & C/C++ –C case statements require ‘break’ statement –MATLAB case statements do not

22. Feb. 9, 2010 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 variables Use full, meaningful names for variables and functions Consider before you start to copy and paste a block of code