MATLAB Coding Standards
  1. Every file must begin with a block of comments.
  2. If there are multiple functions in a file, each must have comments.
  3. H1 comments (the ones that appear when we use the help function) must include
    1. a one line summary to be used by lookfor
    2. name, class, section, TA name
    3. a more detailed description describing inputs, outputs, algorithms used, and the name of the associated testing file. For computational functions, give two brief examples showing the function being used at the command line. Very simple functions that use good naming may only need examples, and not more detailed description.

Good naming is difficult. A name should indicate the purpose of the item being named, whether it is a function, script, or variable. However, naming an integer variable "intVar" does not add any useful information, so follow the programming conventions used in class if you cannot use a better name like "input" or "radius" or "continueFlag".

Do not use comments to make up for using bad names. Spend time on the names instead. Comments should only point out special features of your code, or be used to isolate major sections visually (though this is often better accomplished with whitespace).

Here is bad commenting for bad naming:

n = input('Enter a number: ') %n is for input

Here is better code that doesn't need commenting:

user_input = input('Enter a number: ');

Here is bad commenting for bad naming:

r = 3; %is the radius
w = 2; %is the width

Here is better code that doesn't need commenting:

radius = 3;
width = 2;

If you aren't sure, ASK!

  1. Useless or incorrect comments may be penalized.
  2. Names for all variables and functions must clearly indicate their purpose, with the few exceptions for variable names discussed in class. If you are not sure about an abbreviation's readability, don't use it. Use underscores or camel notation (e.g. getCylinderWidth() to separate multiple words.)
  3. Defined constants, and only defined constants, will be named with all caps. Use underscores to separate multiple words in constant names.