| /project/ix/ | General area for IX work |
| /project/ix/development/ | Where new versions are developed |
| /project/ix/development/jeff/ix-1.x/ | Some existing code, javadoc |
| /project/ix/development/jeff/imports/ | Some imported code |
With so many people working on IX, and the amount of software we're going to produce, I think we're going to need a source code control system sooner or later. CVS is popular, it works in a reasonable way, and it's been used successfully for a number of large projects including ones where the work is done at a number of different internet sites. The main difficulty would be if it didn't work in a nice way for people using Windows.
I'm not sure whether we should use source code control right from the start or wait until our first versions are done (or maybe longer).
I don't know how controversial source code control might be.
It's probably awkward to make big changes in the shape of the directory tree or in file names (and hence in Java package names). That argues for not adopting source code control "too soon".
The issues depend in part on whether we're using a source code control system. Source code control would allow us to let anyone change anything, if we wanted to, and would let us get back all earlier versions. Without it, we'll need to have more rules.
Suggest some rules
We need to decide on the root name and at least the top levels of the package tree.
There's a convention that has the names begin with the net address of the organisation, big-end first. So "com.sun...." "uk.ac.ed.aiai...". But that's awkward, and I think Austin might feel that IX isn't confined to AIAI or even the University of Edinburgh. So probably we should start with "ix." rather than "uk.ac.ed.aiai.ix.".
I think the main subdivisions of IX will do for the next level. So we'd have "iplan", "iview", "ip2", etc.
I also think there should be an "ix.util" package in which we put generally useful, low-level utilities.
In the work I've done so far, I've defined a Debug class in the util package to contain some basic debugging tools; and I think that's a good idea.
I have a Perl program that can be used to do most of the work when changing the top level(s) of the package names. It was used to change "oplan" to "ix". (Note that file names and package names have to be changed together, making it especially tedious to do it by hand. Source code control creates additional problems when doing something like this.)
How should we designate and manage versions?
For O-Plan, we use release date plus a major.minor version number that changes when we do a new "official" public release. When we make changes after such a release, we put a "+" after the version number and rely on the release date for finer distinctions. This is not quite a standard approach in the software world, but it's worked pretty well.
An additional complication with IX is that we will sometimes be doing a new release of all of IX and sometimes just a new release of some particular system (such as I-Plan or I-P2).
There should be a central place where we put the .class or .jar files for any packages we take off the net or from other external sources, and we should have a way of documenting where they came from so we can get new versions etc.
For a less than minimal version of this, see locations.html in /project/ix/development/jeff/imports/
No one likes being told how to write their code, so I think we should keep this light. Nonetheless, it's a lot easier for people to work together if they can read each others code easily, and that means not having a bunch of radically different styles.
I'm inclined just to say "like in good Java texts such as ..." plus a small number of naming and capitalisation conventions. (Also how we should use javadoc.)
One issue is whether the "variables" that are really fields in data structures should be distinguished in some way from local variables. Against: I cannot think of any language in which there's such a convention about global variables - so it can't be all that hard to see which variables are local. (Common Lisp has a convention that's almost one for globals, though.) For: you can easily end up with a large number of "fields" so that it's useful to be reminded when you refer or assign to one.
We should have a common way of doing debugging output rather than have everyone use their own ad hoc method. I'm not sure how the output should be controlled. One approach is to have module and level parameters on each call and some global way to specify for which combinations the output should actually appear. A problem is that we don't want to construct the strings if they won't actually be printed, and I don't know of a good way to combine all that in Java.
We should make sure everyone knows how to use Java 2 collections.
Selected examples:
I have a good way of doing this for Lisp, but I don't know what people do for Java. (The Java language is missing some features needed to doing it the same way I did in Lisp.) It's a huge help to be able to test after making changes, though; so I think we have to do something about this, and if we wait too long it will be too much trouble.
One reasonably straightforward approach is to write an testing application for each module, with a little support from a Test class such as this one. Here's a (probably not instantly clear) example. One problem is that only a very limited range of literals can appear in Java source code. Hence the example's use of constricts such as
It's very useful to have a description of every change, for understanding why things are the way they are later on. Some changes should be recorded in the file(s) in which they're made, but I don't think it's a good idea to handle every change that way. I find it more useful to have a central log in which there can be descriptions of the reasons for changes, output samples, statistics, or whatever. Probably instead of one central log there should be one for each major "subdivision" (each top-level package?).
It's also useful to describe every bug, what caused it, and how it was fixed, because bugs have a tendency to recur and it's extremely frustrating when you can't remember what you did last time. This can probably be done in the change log.
The big problem is: how do we get people to do a good job of writing these notes?
Do we write applications or applets or both? We can do some things to reduce the differences, such as having a common way to get the values of command-line arguments and parameters in the "applet" tags.
I think there are still problems using Swing in browsers.
We should look into "just in time" compilers and other implementations that can give us more efficient execution than JDK. (Actually, JDK may contain a "just in time" compiler these days.)