Last modified 10 years ago Last modified on 2008-05-30 20:30:35

Matlab programming best practices used by the USGS WHSC Coastal Sediment Transport Group

1) The first two comment lines should be:

  • ProgramName (case sensitive) - Short description of what the program does
  • An example call
       function ncs = defineRawSonarNcFile( s )
       % defineRawSonarNcFile - Initialize a netcdf file for sonar data
       % ncs = defineRawSonarNcFile( s )
    

This enables painless directory-level help with help directory_name Punctuation other than the hyphen looks ugly, because help directory_name will inset one.

2) Use structures as calling arguments and return values. That way, additional input and output can be added without breaking calling programs.

3) Make sure there are no misleading comments. Special credit: Add useful comments.

4) Indent the code. Use Matlab's smart-indent feature (under the text menu tab).

5) Take a stab at making the code efficient:

  • Get rid of loops
  • Pre-define and pre-allocate space for arrays and matrices
  • Use the Matlab programming tips to help with efficiency

6) Don't list calling routines as part of the documentation...they can change without touching called routines

7) Don't use suffixes like your initials or the year in filenames to designate a "version" of an existing program. Either fix it, or rename it for the new purpose.

8) Remove explicit references to versions and dates...SVN does this. Consider using the SVN auto-up date feature

9) Remove files when they're no longer used to avoid confusion about which programs are active.

10) If you use hold on, be sure to also hold off.

11) Include USGS boilerplate from m_cmg/trunk/MMstuff/boilerplate