Code Design and Construction

First, some basic words about coding.

1)

Decide on the solution scheme and make every attempt to make sure that it works. The most time consuming bugs to fix are mathematical, not computer bugs. The more work you do before actually coding something in order to assess whether it is going to work, the more time you'll save yourself in the long run...some of the best computing is done AWAY from the computer!

Use matlab to try out the mathematics and the algorithm. Using matlab allows you to quickly debug and diagnose whether algorithm works, and it also forces you to experiment on small problems, which will speed up the debugging of the mathematical issues. Once you have the thing mathematically debugged, you can move to C, Fortran, $C++$, etc. I consider all programming languages equally terrible: the key is using the best features of all of them, which can be done. So, don't be religious about programming languages, or afraid to try other languages.

2)

Decide on the algorithm and the extent of the how robust you want to make the code based on the following criteria: (a) is this a one-shot code? or (b) is this a production code? Why this decision is very important is this: you want to get to results as quickly as possible. You factor in the amount of time it will take to compute the answer, but also the time it takes you to design a code. For example, if you work on a code for a year just to maximize the speed of a code you should remember that the code is now one year old by the time you use it and it might be better to spend only one month on the code and already have 11 months in the balance that you can use to run the code. A one-shot code is preferred. On the other hand, a production code is preferred if the code will be used a great many times, or by other people other than yourself. In this case, software engineering should be geared to increase its efficiency and/or to make it robust so that others can use it with minimal problems.

a)

In the first case, you want to provide accurate results. Will be used to get results quickly and then the code is no longer of use...if your programming is very modular, however, each module can be stored for later use in your ``Tool-kit'' should at some later time you need it.

b)

Software design is crucial $\rightarrow$ take the time to optimize both the operation and scheme.

3)

Make estimates of computing and storage requirements as early as possible.

4)

Write code on paper and do an analytical estimation of its properties.

5)

Implement using matlab (forces you to keep problem small). The other nice thing you'll get from the matlab code is a good test to benchmark your bigger codes once they are built.

6)

Do not reinvent the wheel $\rightarrow$ use (good) developed code, when available. There's tons of this stuff out there. Mostly developed by specialists in each particular algorithm or mathematical area.

7)

Keeping a modular design enables you to develop a library of software.

8)

Date and put your name on each part of your code. Do not erase a piece of code until you know that the next version is always is superior, but keep them organized. You might want to have a directory (which I call the sandbox) in which I dump all the old versions. I do a sandbox cleanup periodically. I also carry a simple ``diary'' in which I enter comments on the code's progress. This is especially helpful if I have to leave a particular project for an extended period of time and then want to remember as quickly as possible where I left off.

9)

A good rule of thumb is not to make any function or subroutine more than 1 page in length. This forces you to keep some modularity and makes program debugging a less messy affair.

10)

Yes, comment thoroughly your code. However, I usually make the thorough comments ONLY after I know the code works well. Often times you put in comments that after the code has been worked on are no longer relevant...these comments just add confusion.

11)

Use descriptive names for variables and don't make them single letters...these are a pain to find using an editor.

12)

Use complex coding only if it achieves an improvement on storage or speed. Gratuitous clever coding is useless.

10)

Write README's with usage instructions, changes, bugs, etc.

11)

Test, test, test your code.