Coding Standard for Physics 241
Code Organization
Entity Naming
Names
Files
Statements
Other Typographical Issues
Coding Standard for Physics 241
Code Organization
Try to use the 4D method to organize code.
D: Document -- D: Define -- D: Derive -- D: Display
I have seen another author call this method ``DSMV''
D: Document -- S: Setup -- M: Model -- V: View
Document: For a function named 'greatFunc', a 'help greatFunc'
should provide the user with the purpose of the function.
Further, there should be a USAGE: comment which the user
should be able to cut and
paste into Matlab and have the function run sensibly.
Define: The define, or setup part of the function defines variables used, and
gives them initial values. Arrays may be initialized to the correct size
if necessary. (In a large program, the setup step might be its own m-file,
called first). Since this is physics, all definitions should include
UNITS! Suggested default values are also helpful to the user.
Derive: The work gets done in the derive, or model section. The physical equations are called. Several
m-files may comprise this section, each implementing different aspects of the model.
The model should generate results, typically an array or matrix that is the
solution to the problem.
Display: It is good practice to separate Display from model. Display is likely to changeas one explores the data. Multiple display scripts can be written. One might
plot the data, one might tabulate it, and a third might animate it.
All comments shall be placed above the line the comment
describes, indented identically.
Being consistent on placement of comments removes any question on what
the comment refers to.
Every function shall have a comment that describes its purpose.
Entity Naming
Variables shall be lower case.
Global variables shall be upper case.
Constants shall end with an upper case C.
Variables which represent a number or a count shall begin with an upper case N.
Names
Use sensible, descriptive names.
Do not use short cryptic names or names based on internal jokes.
Exception: Loop variables and variables with a small scope (less
than 20 lines) may have short names to save space if the purpose of
that variable is obvious.
Variables with a large scope shall have long names, variables with a small scope can have short names.
Scratch variables used for temporary storage or indices are best kept
short.
A programmer reading such variables shall be able to assume that its
value is not used outside a few lines of code.
Common scratch variables for integers are i, j,
k, m, n for characters c and
d. Since this is physics, x, y and z
shall generally be assumed to refer to coordinates.
Files
Each file must contain a revision marker.
Statements
All case statements shall have an "otherwise" label.
Even if there is no action for the otherwise label, it shall be included
to show that the programmer has considered values not covered by case
labels.
If the case labels cover all possibilities, it is useful to put an
"Error" statement there to document the fact that it is impossible to get
here.
An "Error" also protects from a future situation where a new
possibility is introduced by mistake.
Other Typographical Issues
Do not use literal numbers other than 0 and 1. (No "Magic" numbers)
Use constants instead of literal numbers to make the code consistent
and easy to maintain.
The name of the constant is also used to document the purpose of the number.
If converting feet to inches, multiply by "foot_to_inchC" rather than by
"12". If calculating the weight of a mass, multiply by "gC" rather than 9.8.
If running a simulation for every ball in a box, write
for i=1:Nballs rather than for i=1:135.
Generated by R.Sonnenfeld 2006-08-20 using Coding Standard Generator version 1.13.