Introductory Programming
Fall 2006

I had a chance to read your Case Study III reflections, and I
was struck with the number of comments that pertained to MATLAB
programming.

A lot of what I read was good advice, which reminded me that we
haven't talked about the programming process for a while.

Here are some suggestions prompted by comments I read:

1) Readable code is debuggable code, so

   a) Give variables names that are meaningful, or at least not
      misleading.  Use naming conventions (like capital letters
      for matrices and vectors).  Any constant that appears more
      than once should be replaced by a variable.

   b) Write comments to document _non-obvious_ aspects of the code.
      Good comments contain more information than the code; they
      should not be redundant.

   c) Indent your code correctly to make the structure apparent.


2) The best kind of debugging is the kind you don't have to do.

   a) Start with a simple program that works, add new features
      gradually, and test as you go!


3) Use functions to organize your code.

   a) Function names act as a kind of documentation.

   b) Thinking about input and output variables makes you think
      about data flow through your program (who needs to know what?)

   c) Once a function is complete and tested, you can forget about
      how it works and just use it.


4) The hardest bugs aren't in your code.

   a) Before you start coding, double-check your model!
      Also, units, units, units!!!

   b) Start with a model that is simple enough that you know
      what the correct answer should be.  For example, start
      with a scenario that has an analytic solution.

   c) Make the program check itself!  For example, you could
      check for energy conservation after each time step.

   d) When you are validating code, make sure that the validation
      is correct.

   e) Always be 100% sure that the code you are running is the
      code you are looking at.


5) How to get out of debugging hell:

   a) Look for the bug balance point, the point in the program
      where you think it is equally likely the the problem is
      before or after.  Try to test at that point.

   b) Use semi-colons to suppress unnecessary output, and then
      remove semi-colons judiciously to display and check intermediate
      results.

   c) Use plot to display and check intermediate results.  It is
      worth putting some time into building scaffolding that helps
      you debug.

   d) As you read through each section of code, ask yourself, "What
      would happen if this line of code was wrong?"

   e) Take a break and clean up your code.  Fix the indentation,
      replace bad variable names, break big chunks of code into
      functions, add comments to each block of code.

      You might see the error or you might see a change in behavior
      that leads you to the error.

 
6) How not to stay in debugging hell:

   a) Don't make random changes.  Stop and think.

   b) Don't let MATLAB lead you by the nose.  The goal is to
      make the program right, not just to make the error messages
      go away.  Don't turn a syntax error into a logical error.

   c) Don't get too attached to your code!  Code that doesn't work
      has no value, no matter how long it took to write.  Be ruthless.


Newton's method
---------------

Try this at the MATLAB prompt:

format long
a = 4
x = a
x = (x + a/x) / 2

Repeat the last line several times and see how quickly it
converges on the right answer.

Why does this work?

1) Write a function called mysqrt that takes a number
as an input variable and that returns the square root of the
number computed using 5 iterations of Newton's method.

What if it takes more than 5 iterations to converge?

Why not just use fzero?


2) Write a function called testsqrt that takes a vector
as an input variable and that computes the square root of each of
the elements using both mysqrt and the MATLAB function sqrt.

For each element in the list, the function should calculate the
relative error, which is

(estimate - actual) / actual

where estimate is the estimated root computed by Newton's method
and actual is the ``actual'' value computed by the nice people in
Natick.

testsqrt should return a vector of relative errors.

3) Test your function with a vector like linspace(1, 100)
and plot the result.  What does the relative error tell you about
the number of correct digits?

4) Increase the number of iterations in mysqrt and test it again.
How does the relative error change as you increase the number of
iterations?

5) Find as many roots as you can of e^x - 3 x^2 = 0