MATLAB Style Guide

[under construction]

Written by David I. Schwartz, Fall 2002. Some portions are adapted from previous CS99 and CS100 style guides from Fall 1998-Summer 2001 and Chapman's MATLAB textbook.

This guide uses the following notation:

• key term
• element of code
• output
• MATLAB Help navigator: Topic > Subtopic

Many programmers disagree on the "right" programming style, which incorporates these two styles:

• How you write your code.
• How you document your code.

• Help your graders understand what you have done. The more clearly you write and document your code, the more points you will generally get.
• Help others review and use your code, if you produce code after the course. In the "real world" people work in teams and review/use eachother's code.
• Help yourself understand what you have done as you write your code and later if you need to reuse it.  A rule of thumb states that you will have little to no idea what a piece of code does a few months after you have written it, unless you documented it.

This portion lists general principles, or "rules of thumb," that you should consider when writing your code, especially if you develop your style. Many legions of programmers generally agree that you will produce clear code if you adhere to the following principles:

• Follow the specifications.
• Comment your code.
• Provide user documentation.
• Write your code and comments consistently.
• Generalize when possible.
• Avoid redundancy.
• Modularizing your code to avoid redundancy and improve generality.
• Reuse code.
• Implement standard libraries/modules/API classes whenever possible.
• Favor clarity over brevity and ingenuity.
• Indent substuctures.
• Explain major variables, methods/functions, and classes/modules.

Documentation consistents of two types:

• internal documentation
• external documentation

Internal documents are comments, which are inert elements of text that most compilers ignore. In MATLAB, you start a comment with a percent sign (%):

• MATLAB ignores all text that follows the % on the same line.
• MATLAB does not have nested comments, though I wish it did.
• You may write a comment anywhere in a line.
• MATLAB will ignore blank lines, except when you indicate the end of a help text entry.

3.2 External Documentation

A program or package typically includes a user manual, which is a document that  teaches a person how to use your program. For instance, click on the ? icon in the MATLAB interface to pull up the MATLAB Help Desk. Entire careers, such as technical writing, are devoted to the art of writing a user manual. Typically, the user manual is written apart from the software, though sometimes you may supply special kinds of comments that help to provide this documentation. For instance, inside MATLAB function M-Files, you may supply comments that MATLAB's help and lookfor functions will find when a user looks for help on your function.
Top

As you write a title page of an essay or article, you need to title your program with a title block, which is a collection of comments that identify and describe your program at the top of the file. For CS99 and CS100, you have specific guidelines for each assignment. This section discusses the general elements of a title block.

4.1 Name

Choose a name for your program that has some, or all, of the following features, depending on the specifications of the project:

• Describes the purpose of the program.
• Sounds striking, catchy, or original.
• Matches the name of the function/method/module/class that it contains.
• Derives from an acronymn based on what the program actually does.

4.2 Purpose

Briefly explain what the program does. If the program contains modules/functions/methods/classes, you should also briefly list and explain the purpose of these contents.

4.3 Authorship

List the authors that contributed to the writing of the program. You might need to write the authors' job titles along with their names. Sometimes programmers write the date that they started or finished the work next to their names. You may prefer to use a formal description called a revision record, especially if you have multiple authors making many changes, as described in Section 4.4.

4.4 Revision Record

Chapman demonstrates excellent examples of a revision record, which records the date, authorship, and contributions/changes that each programmer has made to the program. See page 51, for example.

4.5 Copyright

[future topic]

Top

Statements are essentially individual instructions to the computer. Think of a statement as a sentence that is composed of words and punctuation. As you would write a paragraph, you need a consistent way to write statements in a logical and syntactical order.

5.1 Rules and Guidelines

The following rules summarize common syntax and style:

• Write your statements from left to right and then top to bottom, since this is the order most compilers execute instructions.
• Write one statement per line with the following exceptions:
• Control structures, like selection and repetition statements.
• "Short" statements, like assignments, that can be clearly and consistently grouped together on the same line.
• Use blank lines as inert spacing  between groups of statements.
• Suppress unnecessary output by placing a semicolon at the end of the statement (see below).

MATLAB provides different kinds of punctuation that affect when and how MATLAB ends statements:

• New Line: Pressing Enter or Return ends the current statement. Beware that many other languages do not have this behavior!
• Semicolon (;): Suppresses the statement immediately to the left and separates two statements.
• Comma (,): Separates statements on the same line without suppressing the output.
• Ellipsis (...): Indicates that the next line continues the statement that is written before the ellipsis.
• Percent (%): Starts a comment, which effectively ends the current statement.

Variables assist programmers in clarifying their code by storing values and expressions. Older languages restricted variable names with constraints in length and lack of case sensitivity. Although you will occasionally confront these irritations, most "modern" languages have abandoned these antiquated notions in favor of flexible variable syntax. This section discusses some of the general syntax that will encounter but focuses on the style conventions.

6.1 Naming

When choosing variable names, follow this advice:

• Match the variable's intent with its name. For instance, if you need a counter, use the variable count.
• Avoid excessively short variable names, such as x, i, and n.
• Avoid excessively long variable names, such as IcouldFeasiblyBeAVariableInSomeLanguages. In fact, MATLAB  will use only the first 31 characters in a variable name.
• Do not start a variable with a number. Many languages forbid this, anyway.
• Capitalize names within a variable to distinguish compound words, such as carModel and termCount. Some people prefer to use underscores (_) to separate names.
• Use uppercase letters to label constants, which are variables that do not/will not change values. See Sections 5.4 and 5.5 for cases that require constants.
• Do not use names that match language keywords or commonly used function/method/class names.
• Ensure that your variable has a value before using it. Except for computer algebra systems, like Maple and Mathematica, you may not use a variable until it has a value.

After you choose your variable names, you should describe their meaning and/or purpose. Since your names should ideally imply thier purpose, you should keep your descriptions very brief. You have different options for where to write the descriptions:

• In the title block at the top of the program.
• Below the title block, near the top of the program. Many languages require you to declare the types of the variables that you use, although MATLAB does not. Typically you will write the description as a comment to the right of the variable.

6.3 Named Constants

To keep your code relatively general, you should avoid a process called hard coding, in which variables and other elements rely on specific values. For instance, suppose you need to input a sequence of values. If you "hard code" your program to accept only ten numbers in the middle of the program, your program is inflexible. Instead, your program should accept STOP values, where STOP is assigned elsewhere, perhaps even to 10. By placing using a variable assignment instead of a specific number, you or another programmer could easily identify the variable that controls the amount of input and change it. Such variables that replace values are called named constants. Sometimes a named constant is so important that you never want the value to change in the midst of the program. Unlike MATLAB, some languages allow you to prevent assignment with special forms of syntax. Variables that cannot change value are called constants. Generally, named constants and constants are written in uppercase.

6.4 Global vs Local

Local variables are visible within a function but not other functions or scripts outside of the function. Even the base workspace, the memory location of the variables that you enter in the command window, cannot "see" local variables inside a function. So, you may use a variable x inside the command window and inside every function M-File with no conflict. However, if you discover that a certain variable value is crucial to many functions, you may label that variable as global to ensure that every function will use the same name and variable. In general, global variables are dangerous, because they are difficult to trace and may substantially alter a program's behavior. So, you should primairly use local variables and save global variables for very specific occasions. Consult Local and Global Variables inside M-File Programming for more information. MATLAB style dictates that you should indicate global variables with uppercase letters, as you would a named constant.

6.5 Predefined Values

MATLAB defines a collection of very useful variables that you should use rather than reinventing. See Local and Global Variables > Special Values for a list.

Top

Expressions are statements that combine operators and values to produce a value.

7.1 Spacing

Instead of writing expressions, like 1+2/(3^(4-5)), which are relatively unreadable, you should insert whitespace in between operators and values. Using the same example, you would write 1 + 2 / ( 3 ^ (4 - 5) ), which is a bit easier on the eyes.

7.2 Parentheses

Rather than relying on operator precedence and associativity to determine the result of an expression, use parentheses to clarify an operation. For example, although the left associativity of minus dictates that 1-2-3 is -4, you should write the same expression as (1-2)-3, which is much more clear. However, excessive parentheses detract from clarity, as in the expression ((1+2)*(2*(1-2))).

7.3 Variables

For a complete set of rules, refer to Section 6.

7.4 Operators

Beware of the difference between equals (==) and assign (=):

• Equals: x==y means that MATLAB evaluates the truth of whether or not x and y have the same value. MATLAB returns either 0 (false) or 1 (true).
• Assign: x=y means that MATLAB stores the value of y inside x. The two variables are not checked for equality.

• Many languages cannot compute exact values with decimal numbers because of roundoff error. Consequently, if you try to compare two apparently equal numbers, you may not get a true result.
• Use abs(x-y) < eps to compare x and y. You may change the value of eps depending on the anticipated round-off error.

Most languages allow for unlimited whitespace, which is composed of spaces, tabs, and new lines around and in between language elements. Although you may not split an element, such as a keyword, you may freely place spaces between elements. Following the model of paragraphs and indentation, programmers have discovered that placing spaces at the beginning of each line, which is called indentation,  improves clarity and ease of programming. This section describes situations in which you will use indentation.

9.1 Structures and Substructures

Rather than referring to code as individual statements and comments, think of each line as either a structure or substructure:

• A structure is an individual line of code.
• A substructure is a group of lines below another group, in which the upper group describes or controls the activation of the lower group.

• Form 1: Join structures

line
line
• Form 2: Separate structures with blank lines

line

line

• Form 3: Separate  substructure with indentation

line
   line
• Form 4: Separate  substructure with blank lines and indentation

line

   line

****
old notes that I using to write new stuff:

9.1.1 Form 1

notion of "equivalence"/preference/group
statements that form a group, or a block, are executed in succession to perform steps in a specific task... thus have same "level" of importants... thus flush with eachother, not indented -- group of statements forms a structure

example? (comments, statements)

9.1.2 Form 2

in between structures/groups of statements insert blank lines to indicate where one task ends and another begins -- may also use
to sep structures from substructures

examples?

9.1.3 Form 3

indentation to indicate a substructure of a structure -- substructure activates as part of the overall task of the structure

examples? (comments with statements, compound statements)

9.1.4 Form 4
combines all forms
 
 

For instance, you may see the following styles:

• Style 1:

% Obtain the size limits from the user:
minSize = input('Enter the min value: ');
maxSize = input('Enter the max value: ');
• Style 2:

% Obtain the size limits from the user:
  minSize = input('Enter the min value: ');
  maxSize = input('Enter the max value: ');

• In Style 1, the input statements are flush with the comment, which is a very standard convention. If the  comment does not refer to statements after the input, then you would insert a blank line after the input for maxSize.
• In Style 2, the input statements are indented, which is a less common convention, but perhaps more clear and consistent with other substructures. Since the input statements "belong" to the comment, they are indented underneath. The indentation helps to clarify what statements occur as a result of the comment.

However, you should be aware that not everyone uses this convention. Sometimes it is not relevant, and sometimes there are rules/forces against it. For example, CS312 tends to use a rather different program language to write rather different programs, in which other styles might be appropriate. (Another example is that J and M instructors often use a variety of editors with different methods for formatting.)

You should apply the principle in your own code for CS100, but if you would rather not, keep in mind that your project scores will not suffer unless you make a handful of other errors -- you can get a perfect score if you make only a few errors.

9.2 Statement Comments

9.3 Selection Statements

9.4 Repetition Statements
 

Top

Clearly specify inputs and outputs using "Preconditions" and "Postconditions".

Preconditions specify:

• the meaning of each of the input parameters
• what kinds of data the input parameters are allowed to contain
• constraints regarding when the function can be called, e.g. "X is positive".

• what values are gauranteed to be in the output parameters
• the format (what kinds of data) of the output parameters
• constraints that are guaranteed to be true of the output parameters, e.g. "Y is between input parameters A and B, inclusive"
• any side-effects that the function might have, e.g. input/output interaction with the user, plotting data etc.

• Write a "summary" comment line with the names of the function and input and output parameters and a brief description of what the function does.
• In the comment lines that follow, specify the meaning of the input parameters, taking care to mention if they need to be strings, doubles, matrices etc.
• Finally, clearly specify what values the function puts into output arguments and any other I/O, plotting related work that the function does.