Computing for Imaging Science (SIMG-726)

Programming Project Submission Guidelines

The following are my general requirements from a programming project assignment. A lot of it is common sense, but it helps to state and elaborate on each point. I believe that these requirements should hold to all algorithm development and programming projects no matter what language was used for implementation. The rationale for these requirements is to give you guidance in creating a comprehensive stand alone document that will allow other people (both programmers and non-programmers alike) to understand what your code is doing and gain insight as to what types of answers he or she can expect. This will give them (and yourself) confidence that the answers generated by your code will be accurate. It is not sufficient to simply comment code because anyone who gets to that level should already have an understanding of what they are getting themselves into-especially if they want to make any modifications.

This document should be of the same quality and content as that found in the appendix of a thesis or dissertation describing the method user to solve a problem. As difficult as it is to write computer code, it is even more difficult to read someone else's computer code . As with writing styles, each person will have their own particular coding style which may require some adjustment on the reader's part to grasp the logic of the program. In order to prepare someone to becoming intimate with your code (running your program, reading it, and eventually modify it), you should have as part of your report, the following key sections.

Problem Statement:

This should describe in detail (and in words) the problem and the computational methods/actions being performed by the solution. This is a step which many people tend to overlook before they start writing code. This is critical because if you cannot clearly explain the problem you are solving to another person through words, then chances are you are not prepared to write code any code at all. Describing a problem and how to solve it to a "dumb" computer requires more painful details than you would ever give the normal person. The problem statement should also give the reader an idea of the extent of your problem domain and how general your program is at its current state (Does you program simply add 2+2 or does it solve all the problems in the universe?)

Statement and Explanation of Relevant Equations:

For the most part, you will probably be dealing with computations based on some formula or equation. It is imperative that you include this in you report because a particular computation may have two forms - one that is mathematically compact and intuitive and another that is less intuitive, but more computationally efficient. If you do use the more computationally efficient version of an equation, be sure to also include the more intuitive form as a foundation for your reader. If a routine has no mathematical computations, but merely performs supporting tasks (such as file input and output) then explain what the routine is expected to do. Make any references to textbooks, articles, other pieces of code, or people that you consulted in designing and implementing your algorithm.

Flowchart Giving an Overall View of Your Process:

This does not have to be a formal flowchart. It could be just a set of balloons with words in it connected by arrows describing the general steps in the overall process of your program. I can be used as a guide in modularizing your program. It also give the reader a map of the interrelations of the different functional components. This makes it easier for them to know what files to modify.

Variable List and What They Represent:

Create a table which you can reuse as a "variable" dictionary in you comment codes. Even though you might think that a variable name is obvious, another person may find it meaningless or ambiguous. It helps to also list your favorite temporary variable names up front. Pl--s- -s- l-ng v-r--bl- n-m-s b-c--s- y-- h-v- b-tt-r th-ngs t- d- th-n pl-y wh--l -f f-rt-n-. (Our category is variable name. Would you like to spin, buy a vowel, or solve the puzzle?)

"Self-User's Guide" and Testing Procedure of Your Program :

Trust me, you'll need it for programs of any complexity. A "Self-User's Guide" is especially helpful for command line driven programs as well as GUI front ends. In 6 months of disuse, even you won't remember what your program does.

The testing procedure is probably the most critical step besides the actual design and development of your code. You should document how you convinced yourself that the code is working properly. What data set did you use to verify this? How did you verify this (Mathcad, Excel, calculator, slide rule, abacus, psychic hotline, etc.)? Your test data sets (always present at least two sets) should be small enough that you can easily reproduce the results by hand with a calculator or a spreadsheet. In the case of images, the two data sets should be both patterned and random (e.g. 0,1,2,3,... and 233,0,5,89,10,...) and it does not hurt to reverse the order of the pixels either to create a 4th and 5th data set. When working with images, make sure that you do tests on the smallest possible images (2x2, 3x3, 4x4 - whatever makes sense). Just as important as the input data is a standard output data set to which answers can be compared. This is crucial because when your code is ported to another platform or architecture, your ability to reproduce these answers will be you assurance that all is well. If the program generates the correct answer on one machine, but not on another, then this is a sign that there is a potential flaw in the implementation of your algorithm.

Program Listing and Output:

This should include a heavily commented listing of your program, sample input and output, and hardcopy copy of spreadsheets, graphs, and images (both input and output). Your program should also have an RCS history in the top comment block and you should also include any Makefiles necessary for program compilation.

Lastly, If for some reason your program cannot compile or does not work properly, document that fact and detail the symptoms of the anomaly with the tests that you tried. Make a hypothesis as to what you think the problem might be. The person who inherits your code will thank you because they then do not have to reinvent the wheel by trying to reproduce your thought process. Doing this might actually help you solve the problem. If not, the person who inherits your code will just occasionally curse you instead of tracking you down and stalking to the ends of the earth and annoying you to no end.

Email: rolo@cis.rit.edu