The course discusses design of generic software libraries, and aims at providing the understanding on how to design libraries that are both general and efficient. Also, the course surveys many language mechanism that can, to a varying degree, support development of generic libraries. The goal of the project work is to deepen and strengthen understanding of the design principles discussed, and to offer a practical hands-on experience to generic programming.
Possible projects are:
If possible, try to find a project idea that is of interest to you, and ties into your research. If you need help in finding a project idea, I will provide a set of suggestions. (See the Project slides.)
Possible changes to the schedule will be announced in class, or on these pages.
The final report of your project should consist (at least) of the following parts.
Even though these are often separate volumes of in a documentation of software, for the class project keep the parts in a single document. Note that usually source code is not part of documentation, here you may want to include that in your document as well.
The User's guide should begin with an overview section. The overview section is a crucial part of the documentation and you should make sure it really does give an overview. Before writing the overview, consider the following issues:
In particular, the intended audience is not the course instructor. Rather, think of a professional programmer. It is a good idea to describe how much, and what kind, of knowledge you are assuming from the audience.
Do not dive into too much detail in the overview, save that for later parts of your document.
After the overview, the user's guide should contain tutorial material, examples, discussions of normal usage, pitfalls, etc. You do not need to go into extremes with such material for the purposes of the class project, but provide enough to make your project accessible to others.
Include a bibliography of your sources (journals, web sites, your own previous projects, etc.) for concrete algorithms, data structures, or other information relevant to your software. It may make more sense to have a common bibliography for your entire document, rather than just for the User's guide. Use your judgment.
See how to use the STL documentation for description of how, e.g., concepts are documented in the SGI STL documentation. Follow these guidelines as is appropriate for your project.
Describe the most important design decisions. Why the interface is the way it is? Why were particular algorithms or data structures chosen?
One purpose of this section is to avoid extra work in the future. Unless the thinking behind various design decisions is documented, the same thinking process may have to be repeated later if the design is re-evaluated. In particular, documenting the reasons why other (inferior) choices were not selected is helpful.
Test for small cases, including all boundary cases you can think of, such as empty sequences, one-element sequences, graphs with no edges, graphs with more than one parallel edges, and so forth. Test for large cases as well; if possible, define an acceptance routine that checks correctness of result by some means.
If applicable, you should include timings (you want to make sure that the complexity guarantees that you documented in your reference manual are realistic). Test for large cases, measuring performance for large randomly generated inputs of different sizes. Document all necessary detail (hardware platform, compiler, optimization flags, ...) to allow someone other than you to repeat the same measurements.
The requirements of including full source code in your document does not apply if there is so much of it, that including it all would be ridiculous.
Follow the structure of the final report to the extent possible. You can then hopefully reuse much of your preliminary report as part of the final one.
In the first part (User's Guide), give a brief overview of the goals of the project, written as though the design and implementation were already complete and you are describing it to a prospective user of your software. This overview should concentrate on giving a brief description of the components you are developing, and the key idea(s) of the generic algorithm(s) or data structures involved, including why you expect these components to be useful. End with a bibliography of your sources (journals, web sites, your own previous projects, etc.) for concrete algorithms, data structures, or other information you plan to use in the project.
Reference manual will not have much of content at this point, but there should already be some discussion on the design issues, as well as a test plan. Do not include source code at this point.
Write well. Good and clear language is important, even (or especially) in technical documents. In particular, check spelling and grammar — spelling with an automated spell checker — before submitting the final report to me (or before submitting any document to anybody). Remember, you are writing a piece of generic software, to be used by many for varying purposes. It is thus worthwhile, and necessary, to document your software very well.