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

How you write your code.

How you document your code.

When learning how to program, not only
do you need to learn how to write correct code, but you need to write clear
code that will serve the following purposes:

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.

Ultimately, you will develop your own
"writing style," but until you do, you should strongly consider the advice
that this guide contains. You should also consult with MATLAB
> Using MATLAB > Programming and Data Types > M-File Programming,
You will look here for most help pages for this document.Top2.
General Principles

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:

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.

For more information, go to MATLAB's
programming guide (see Section 1) and scroll to the bottom of Functions
> Basic Parts of a Function M-File.

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
4.
Title Block

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.

Write the name at the top of the program.

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.

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

5.2 Punctuation

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.

Refer to help punct for a brief overview
of these and other forms of MATLAB punctuation.Top
6.
Variables

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.

6.2
Describing

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.

Generally, you should avoid introducing variables in the
"middle" of your program.

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.

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.

Beware of round-off error:

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.

A lines of code typically have one
of the following forms:

Form 1: Join structures

lineline

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

The following sections demonstrate
the use of these forms.

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

9.1.1 Form 1

notion of "equivalence"/preference/groupstatements 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 useto 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

In both versions, the comment describes
the input statement. Thus, the comment starts a new structure, which includes
the input statement as a substructure:

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.

This principle is especially important
because good programming involves breaking larger problems into smaller
problems. The way the sub-problems fit/nest into the larger problems should
be immediately apparent from the code for maximum clarity. The principle
above provides that clarity with a simple, unifying principle consistent
with our other conventions for indentation.

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.