5 Projects
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.
5.2 Types of projects
Possible projects are:
-
Develop one or more generic algorithms, or other generic components,
to an existing generic library (basically STL or BGL).
This means analysis and development of concepts,
designing the components, implementing them,
writing a test suite, and writing a high-quality documentation
of the components.
- Write a generic library for some domain. Obviously, you need to
settle for something less ambitious than STL or BGL to stay within
the time limits. Again, the project consists of
analysis and development of concepts,
designing the components, implementing them,
writing a test suite, and writing a high-quality documentation
of the components.
- Something else. If you have a project that is related to generic
programming, and you would like to work on that, let's discuss it,
and see if it would qualify as a class project. Examples of projects
of this third category include tool development for generic programming,
work on language support for
generic programming, work on theory for generic programming,
and development of libraries that exploit semantic constraints.
This is not an exhaustive list.
5.3 Project ideas
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.
The slides from Tuesday Sep. 26th class with project ideas
are here (and here as 4 slides per page format).
5.4 Schedule and dead-lines
-
Tuesday, October 10, each group must have a plan for their
project. In practice, let me know by email the following information:
-
Project title
- Brief summary of the goals of the project
- List of sources (articles, web sites, etc.) you will base your work on.
For instance, sources of concrete algorithms.
- Tuesday, October 31, a preliminary report on the project.
I will meet with each group on the following week;
this report will serve as the basis for discussions.
- Tuesday, November 2 – Friday, November 9, individual meetings
with each group.
- Project presentations will be on November 28th and 30th, and on December 5th.
- Thursday, December 14th, final reports due.
Possible changes to the schedule will be announced in class, or on these pages.
5.5 Final report
The final report of your project should consist (at least) of the following
parts.
-
User's guide
- Reference manual
- Design document
- Source code
- Description and results of testing
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
should include that in your document as well. I encourage to try the
literate programming approach for your documentation. Two
fairly simple tools for literate programming are
Noweb
http://www.eecs.harvard.edu/~nr/noweb/, and
Nuweb http://nuweb.sourceforge.net/.
There are others too.
5.5.1 User's guide
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:
-
Who is the intended audience.
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.
- What is the right level of discussion for the intended audience.
Do not dive into too much detail in the overview, save that for later
parts of your document.
- What terms need to be defined to convey the main points to the
intended audience.
After the overview, the user's guide should contain tutorial material,
examples, discussions of normal usage, pitfalls, etc.
You do not 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.
5.5.2 Reference manual
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.
5.5.3 Design document
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.
5.5.4 Description and results of testing
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.
5.5.5 Source code
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.
5.6 Preliminary report
Follow the structure of the final report (see Section 5.5)
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.
5.7 Miscellaneous
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.