Project Planning

							         Core Programming Module
               Best Practices

       Core Grant Programming Module
       Best Practices (Coding Conventions)
       General Best Practices
       MATLAB Best Practices




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.


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

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




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




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

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

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

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)
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)


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

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)

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”


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



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

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)

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

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

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

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




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


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
Feb. 9, 2010        UHCO Graduate Course in MATLAB