Elements of programming style
(with apologies to Strunk and White, computer scientists and computer
sciences
departments everywhere)
[originally written 8/28/06; last modified 8/29/06]
- Plan your code; Code your plan.
Work out the math
with pencil and paper before you sit down to program. Before you
write a line, decide what overall operation it is that you wish the
code to perform, and then sequentially outline the steps required to
achieve this end. This outline, as comments in your code, can
then serve as an organizer and as a way to code and debug each component of the
program. Then you can go to the task of translating your plan and
the math into code.
- Save and backup regularly.
You never know when a
disk will fail, power will go out, coffee will spill, undo will run out
of steps, programmer's high will strike ... You can use matlab's diary
function, and you can save early bits of scripted code that work but
that you decide to improve upon. At the end of the day, be sure a
copy of your work exists on two separate disks in two separate
computers in two separate buildings. Having paper copy of anything
really crucial is not a bad idea.
- Comment extensively.
Comment each logical section
and any step that is not terribly clear to you. Get a friend to
see if she can make sense of the logic (i.e. code plan) of the
program.
- Script everything.
The command line is fine for
testing lines of code, but don't use matlab as if it were a
calculator. Write code lines into a script via an editor
(matlab's edit function; your favorite external editor) and edit them
there. Then to test, all you need do is run the script by
calling it's name.
- Don't type if you can help it.
Unless you're trained
professionally you probably make lots of typos. Avoid typos by
using copy and paste. Copy and paste bits of code you've already
written and edit those in a
script in a context-sensitive editor (e.g. edit)
that will recognize and colorize functions, close parentheses,
automagically identify nested loops, and keep a record of past typing
so you can undo/redo easily. Use the shell-like matlab command
line to repeat past commands by using the up/down arrows, tab to
autocomplete a function or command, and return. Put variable
descriptions into comments upon declaration; keep variable names short.
- 1 line of code = 1+ "bugs".
A rule of thumb.
As you write an original code, expect to subsequently spend
considerable time making it work. The most common coding bugs
(mistakes) are syntax, but the more serious and difficult ones to find
and correct are mistakes in telling the computer what you want it to
do (e.g. the computer does what it's told, but that's not what
you wanted to accomplish). See Plan your code for the best
way to avoid this problem.
- Test with small examples.
Before you set the
computer to attack a large problem, test the code out on an analogous
but small problem. If it does what you expected, great; you can
be confident that the large problem is just a matter of crunching the
numbers. If not, you won't have wasted a lot of time waiting to
find out your million element matrix is filled with NaNs. Go back
to debugging until
the small example works.
- Test with known examples.
Before you set that code
loose on your data, with unknown and to be interpreted results, try it
out on a test case where you know the outcome beforehand. For an
analysis code, feed it a synthetic dataset whose properties are
well-known. Some examples are sinusoidal waves,
red/white/blue-spectrum random values - often best tested using small examples.
- Optimize.
Great! The program works. Now
can it work faster? Use
the commands tic,toc
to identify bottlenecks in cpu usage. Use whos to identify
unused variables, and see if you can use algebra to minimize memory
usage. Saving to disk in binary
format or matlab workspace
format produces smaller files, especially for large matrices used only
in matlab; save in ascii format only for exporting to other software or
for external uses.
- Check your results.
Now you've run the code and it's
on to the important work of making sense of the results. Before
you waste a lot of time performing further analyses and interpreting
garbage, make sure the results are legit. Do they agree with your
research hypothesis? Common sense?
Prior understanding of the data (units, amplitudes, ...)?
- Generalize. Although
you wrote a program and it
successfully solved the problem at hand, what can you do to use the
code for any of the same class of problems? Make sure there are
no or minimally hard-coded values; instead, set these up front as
variables. Consider rewriting your script
as a function.
Back to
Schedule/Syllabus.