The architects oversee the overall structure of the program, the interfacers handle the user interface portions of the program, the networkers build any modules related to the web or internet, the adapters construct the artificial intelligence portions of the program, the modelers come up with the user modeling and polling portions of the program, and the webdevelopers improve and expand the website.
Each team will be as independent as possible,
but interdependencies are unavoidable on some parts of the project
because not all parts of it are equally hard
and because two or more topic areas are needed for certain parts of it.
For example: the
website might be a joint responsibility of the interfacers and the networkers,
the control interfaces might be a joint project of the interfacers
and whichever team is building a control interface,
the database might be a joint responsibility of the adapters and the modelers.
The architects are responsible for creating the overall design, for documenting the overall design, and for making sure that any inter-team problems are resolved.
For any team to make a change in their portion of the architecture (the interfaces that that team's code presents to the rest of the system) their representative must first argue the case with the architecture team.
The architecture team must also decide on and oversee
the coding and documentation standards,
and decide on and oversee the build, smoke, and code check-in procedures
Each team will first produce a scope statement---a web document detailing what they will do as their portion of the project. These goals will be outlined in stages of completion.
For example, the interface team's scope statement may promise to first put up a random display of points, then a week later a display of points with locations mapped into clusters, then a display of icons with locations clustered, then a 3D display but with only primitive clustering, then a 3D display with more detailed layout, then a 3D display with detailed highlights, then a 3D display with landmarks and audio cues, then more controls for the user, then more animation and interactivity, and so on.
Similarly, the networks team might first promise to build a primitive mail handler in Perl, then using that as scaffolding translate it to Java, then build on that to produce a plain vanilla interface with no smarts, then the following week add a better interface more in line with the overall interface, then more smarts to the data clustering, then more smarts to the analysis, then an even better interface, and so on.
Each team's scope statement
will be reviewed by the architecture team for appropriate fit
and level of difficulty.
Every team must document everything it decides and everything it makes. That documentation must be produced in real time as decisions are made (even before any code is produced) and then put up on the website as the project proceeds so that other teams can consult any team's documentation at any time.
Documentation and coding must proceed in parallel. It is not permissible to postpone documentation for any purpose. Publicly documenting on the web what we do as we do it is nearly as important as doing it at all. It doesn't matter how good our work is if we can't communicate its wondrous qualities to the world.
Each week we will review the work posted so far, looking for quality, readability, and understandability. Each team will have to produce well-structured English with no spelling, punctuation, or grammatical errors.
Documentation includes in-line source code documentation
all the way up to package-level descriptions of major
modules. All documentation at all levels must be extensive and well-written.
A good Java programmer with no prior experience
must be able to understand any part of the implementation
simply by reading the documentation for that part.
We will have to generate an API so that outside programmers can rely on our code and modify bits of it secure in the knowledge that other bits of it won't break.
To make sure that different packages fit together, each team will first write
Java interfaces (for example,
public interface Entity)
to specify interactions with other packages.
These interfaces should be completely agreed upon, and compiled, and
documented, before any other code gets written.
Subsequently, no team should know (or care) much about any classes
outside their own packages;
only the relevant interfaces can be used.
The implementation of the interfaces will then be easy to change, if required.
The set of all public interfaces then becomes the API for our entire project.
The week after we agree on an overall architecture we will attempt our first build. Weekly builds before classtime will then continue until the end of term, so there will always be a version of the program as an executable.
Each week will (presumably) see improvement in our program's ability to fetch data, parse data, analyze data, link data, cluster data, map data, display data, accept user feedback, and alter behavior based on user feedback. So every week we should see measurable improvement in our program.
Teams that break a build can expect to be held accountable for breaking the build with the proviso that any team attempting something innovative that week will be given some slack if they don't manage to produce a build-safe version that week. In other words, a build-breaking team had better have a very ambitious subproject ongoing that week.
The necessity of passing the weekly builds should not be allowed to stifle
On the other hand, adhering to the build cycle is very important
so that we can all always see how far we've come
and how far we still have to go.
So anyone with an innovative idea should first present it to the architecture
team for approval.
Since not all of the design is fully fleshed out,
innovation is strongly encouraged and will be strongly rewarded.
Besides passing the build, each team's code must pass a weekly cumulative smoke test (as in: "put it in and see if it smokes"). The smoke test is designed to exercise whatever code the team added that week plus the cumulative portions of previous smoke tests passed in previous weeks.
Creating the smoke test for each team will be the responsibility of the team "downstream" of the team in question since they are the ones whose code most depends on the upstream team's code.
Besides the smoke tests, each team will have to test their own code.
Every major class should have a main() method with suitable tests for that
class, whether or not the class runs as an application.
Once we agree on the architecture, weekly seminar meetings will consist of presenting work, discussing the various problems that have arisen that week, and brainstorming solutions to those problems.
Each team will present the work they did the previous week, along with pointers to the appropriate web documents detailing that work. We will compare that work to the appropriate scope statement and discuss any deviations. It's okay to deviate because it's impossible to predict all contingencies in such a complex project, but any deviations must be documented and defended.
We will also discuss the outcome of that day's build and smoke test. This presentation cycle will continue for the rest of the term except perhaps for occasional guest lectures as the need arises.
Each team should meet separately after the weekly seminar meeting to go over our various comments on their presentation that week and to coordinate amongst themselves who's going to do what during the week. Teammates should keep in touch with each other during the week as well to avoid diverging too far from each other with realizing it.