Introduction

The purpose of the project writeup is to document your efforts and to leave the reader with an understanding of what the code can or does do. You should write this document at the level of one of your peers; i.e., seniors write for seniors. Unless otherwise specified, the project writeup contains the sections outlined below.

The projects will use a literate programming system (LPS) called noweb. The purpose of this, or any of the other LPSs, is to allow you to intersperse English with code and to free you from organizational constraints imposed by compilers. Most LPSs are based on TeX or LaTeX; therefore, mathematics and pictures are easy to include in your code. You are to read Norman Ramsey's article. For even more information, see fibonacci program. This program, when run through notangle will produce a compilable file. On the other hand noweave -html fib.nw < fib.html will produce an html file suitable for viewing.

General Outline

• Introduction. The introduction should explain the purposes of the project. The reader should be able to answer the question of ``where is this project coming from?'' What results are you expecting? How is this related to other projects you might expect the reader to be familiar with? What practical problem does this solve? What are the applications?

• Specification. The specification gives the technical requirements of the project. These requirements should include the preconditions and postconditions. The processing requirements are the behavior of the program. The pre- and post-conditions must be well enough formulated that the behavior is constrained as required. The specification does not contain the algorithmic information---it contains logical information about the input and the output. This information comes from the problem, not the solution.

  The specification may (should) contain all information that constrains the solution. This includes such things as performance limits.

• Algorithm. The algorithm is described, in a literate system, intertwined with the code. The concept is that we do not separate the code and its documentation. The documentation aspect should be tied to the code as outlined in below.

• Testing Plan. Every algorithm needs to be tested or proven correct. In reality, proofs are hard; therefore, one should be prepared to write a test plan for each major procedural entity.

• Performance Analysis. Every system should have some indication of the computational complexity of the system and its components. Timing data should be produced to substantiate the complexity analysis. N.B. This information is usually project specific. Be sure you understand the requirements.

• Results, Conclusion, and Future Work. Every project generates results. These are documented in this section. You, the student, should have learned some things; these are documented here. [I expect every report to have a section or subsection devoted to what you've learned]. If there are data to be presented, then a (sub)section is required. In the Future Work subsection, you should document what you would do differently as well as what features could be added.

• Analysis of Project. What did you learn? Homilies like "I learned literate programming is wonderful" count for 90% off entire project. What would you do differently? What techniques did you learn? What clever things did you do? What bad things did you do?

Documentation Rules for Code

• Each component file must contain the file name, author's name, course number, and assignment identification. A brief overview of the contents of file is required. In noweb, the file name is printed in the page header.

• Procedural entities will contain the signature, preconditions, and postconditions. Each parameter must appear in the pre- and\slash or post- conditions. The behavior of the procedural body must be described. Preconditions and postconditions can be described without resorting to mathematics notation. You are trying to help the reader understand.

• Declarations must be documented as to use. This includes type definitions as well as variable definitions. In the case of extern definitions, the comment should include the location of the defining entity.

• Reasonable indentation rules must be used if not using noweb. Reasonable means that the printed document doesn't have wrap-around lines of code.

• In literate programming, Code is decomposed into ``chunks.'' There are documentation chunks and code chunks. The metaphor that is suggested is a ``two-paragraph'' model. Code is decomposed into reasonablly sized chunks. Each such code chunk is preceded by a documentation chunk. Obvious decomposition rules:
  • Large blocks of code that contain local variables.

  • while statements. while statements should address the termination question. The really appropriate way to document a while statement is with an invariant statement

    .

  • for statements. fors are just whiles in disguise.

  • do statements. Ditto.

  • if statements.

  • switch statements.

  Documentation chunks use proper English and should be related to the specification, not the code, where practical. The description will normally be in the active voice.