Moon Calendar began simply enough.
I was taking the Software Engineering class (CIS 375) at the
University of Michigan - Dearborn.
This course teaches the management of large software projects, with an emphasis on
documentation, user interface design, project scheduling and quality assurance. The assignment required a
significant user interface and an online help system, along with enough documentation in the form of state
transition diagrams, data dictionaries data flow diagrams and testing plans that any poor soul who inherited
the program without benefit of the author's presence would be able to make sense of and maintain it.
Initially, I envisioned a rather simple tool, which would read the system clock and display a picture of
the Moon's phase at that time. Our instructor,
Dr. Bruce Maxim,
suggested that this amounted to little more
than a pounds-to-kilograms converter, and we would need to do something more complex. Thus began what is
technically known as the Embellishment Phase of the project. After mulling over the possibility of allowing
the user to enter dates of their own choosing, the idea of facilitating this entry in the form of a calendar
was hatched. That, and the proposal to display other information along with the phase such as distance and
rise and set times, got the project approved. Dr. Maxim also suggested (insisted) that we include
external links to other pertinent sites within the program.
A quick perusal of what information we had seemed to confirm that Java was a good choice, although I
was concerned about speed; an interpreted language is always slower than a compiled one, and this
program was going to be computationally intensive. Still, we would be able to get the front end up
quickly, test the interface, and worry about performance later, if necessary. As an applet, the project
could be used on many different platforms without modification, and it seemed like the sort of thing
that would look good on the Web, too.
As I thought about the possibility of distributing the program over the Internet, it occurred to me that
this would make a great educational tool for elementary school children. My oldest son is in second grade,
and his school has computers all over the place, all connected to the Net and largely sitting idle due
to a lack of good software to run on them. We decided that this would be our target audience, and began
planning how best to implement Moon Calendar with this in mind.
We next turned to the online help system, which was a major requirement for the project. Since each
field on the display was to be labeled, we decided to make the labels active - clicking on one
would bring up the help screen for that item. We also included a general information button on
each screen, which would give an overview of that screen's functions.
The project had, by this time, split into three distinct parts: the calendar, which would display
a small graphical image of the Moon's phase for each day of the month; the detail screen, which
would present a photographic image of a particular day's phase, along with information on the
rise and set times for the Moon and Sun, and their distance; and the help screen, where we also
decided to put our external links, again using a drop-down list.
Personally, I get quite tired of programs with bold splashes of primary colors, sound effects, and
other gee-whiz effects. This was meant to be an educational tool, and I felt strongly that the
information was of primary importance. For this reason, the interface was kept rather subdued; the
information is meant to come to the forefront, while the program and its algorithmic complexity
fade into the background, as it should be. An initial rendering of the calendar grid with the day
cells delineated by thick lines was rejected, as it tended to obscure the primary mission of the
calendar - to display the Moon's phases. Distinct cells of some sort were still required, because
it is by clicking on these that the user moves to the detail screen. This was finally accomplished
by using a slightly raised appearance to each cell, which is unobtrusive and gives an indication
that here was an element which would do something if you clicked it. The remaining elements were
grouped well off to the side, away from stray mouse hits, and arranged according to function; the
Information button was slightly offset from the main group of controls to indicate that it was
in a class by itself. The program's single Easter Egg also appears in this area. If the user selects
October 1582, the are presented with a rather bizarre looking calendar. Pope Gregory XIII eliminated
10 days out of the calendar at this point, to bring it back into astronomical alignment. These days
are missing from this month's calendar, and require an explanation. If this month is selected,
another button appears, which brings up a help screen explaining appearance.
The same basic design was followed on the detail screen. We also decided to add an Animation feature
here, more for fun than anything else, although it has educational value as well. As the Moon dips
above and below the celestial equator, the angle of the terminator changes, and this is readily apparent
during the animation. This was a provisional feature at first, because I was still concerned about
Java's speed; I wasn't sure it would be fast enough to generate frames at an acceptable rate,
particularly because we had to write our own ellipse drawing routine to mask the Moon's photograph;
Java doesn't provide a way to draw ellipses at an angle. We originally included here a facility
for setting the local time zone, but this was taken out when my son and his friends were utterly
baffled by the whole concept. This would certainly be a feature for an older audience, but not ours.
The help screen is of fairly straightforward design, displaying a text file appropriate to the topic
at hand. We included a Credits button and a drop down list of related Internet sites here, because
it seemed like the place where they belonged.
There was really nothing to be done about bad network connections; these were out of our control.
However, the program does use some auxiliary resources for the Moon photograph and Help files;
if these were missing, we still wanted the program to be useable. To this end, if the program
detects that the photograph did not download, it generates an appropriately sized white disk to
replace it with. If a Help file is absent, it substitutes a short message to that effect. Both
cases allow the user to continue with only minor inconvenience.
Missing Internet links are simply not entered in the drop-down list; in fact, if the program
can't find any links, the list never even appears.
Finally, realizing that schools don't always have access to the latest technology, we included
an alternative message in the HTML file where the applet lives indicating that the user must
have a Java capable browser to use the program.
The Help files are downloaded only once - the first time accessed, they are stored in a hash
table, where they are immediately available if the item is requested again. This works well: the
experienced user doesn't need help, and doesn't have to wait while it downloads. The novice may
need to request help several times for the same item, until it is mastered.
We wanted the calendar to be accurate, and had to wait until near the end to verify that it was.
This was nerve-wracking; as noted, I wasn't very confident in Java's ability to keep up with
our calculations, but I wasn't going to know if this were the case until our deadline was nearly
at hand. Incredibly, the phase calculator worked on the first compile, and proved to be more
than fast enough for our purposes. It can easily calculate the phase of the Moon independently
for each day of a month in under a second, which meant that animations were going to be possible
after all. Sadly, because of problems that some browsers on the market have with memory management,
we were forced to slow the animation rate down to about four frames per second to allow time for
garbage collection. The animation is still quite acceptable, however.
Phases, distances, and rise and set times were compared against worked examples in Astronomy texts,
and also with newspaper listings. These were found to agree for the most part, except for the Moon's
rise and set times, which can be off my as much as forty-five minutes because of the rather simplistic
algorithm we use to compute it. Although this may be improved in a future version, it is close enough
for most purposes, given the vagaries of local horizon visibility. Recently, phases were checked against
historical records from the mid-1700's, and were found to be in agreement.
As one moves farther away from the present time, the accuracy slowly degrades. Although there are more
accurate algorithms available, these are an order of magnitude more complex than the one we use, and
would have a negative impact on performance.
We decided early on to implement Moon Calendar using Java 1.0, because this version is available in
most modern browsers. Although version 1.1 has many features which we could have put to good use,
we wanted to aim for the broadest audience possible. Unfortunately, there are several bugs in both
Java and the current crop of browsers available, which will break Moon Calendar in some ways. Our
Help screen, for example, is supposed to wrap text automatically; on most platforms and browsers
this works, but on some the text scrolls endlessly off to the right. The various screen elements
are inconsistent between platforms, since they are based on their host's peer; this is a problem
which will be addressed when the Java Foundation Classes become available.
The Internet turned out to be the perfect distribution medium, since most schools around the country
are hooked to it these days. I think it's great that we can now develop educational software and make it
instantly and widely available. Developing Moon Calendar was a tremendous amount of fun, and I'm glad to
know that people are enjoying it.
Implementation
After establishing roughly what we wanted the program to do, we needed to decide on an implementation
language. We had heard that Java made building graphical user interfaces relatively painless compared
to ground-up development using a language like C++. We didn't know anything specific about Java, but
decided to give it a look.
The User Interface
We wanted kids from first through fifth grade to be able to use the program easily. The primary
consideration was data entry; dates, times, latitudes and longitudes can be quite a handful both
conceptually and in terms of typing for this age group, so we batted around a few ideas to keep
this as simple as possible; nothing can ruin a good program faster than an interface which makes
it painful to use. We decided typing was an unacceptable means of entering information, and chose
to make use of drop-down lists instead. If these are made large enough, even the youngest kids can
select the dates quickly, and they are very easy to learn. Further, they automatically provide for
data validation; we would never have to worry about an invalid date or time being entered, because we
could restrict the selections to proper values only. This decision forced the date range of 3999 BC to
3999 AD upon us; our date algorithms only work back to 4713 BC, and we didn't want to deal with the
algorithmic logic needed to accommodate a '4' in the millennium position. This still covered the range
of most historical events; the only remaining problem was what to do about the year 0, which doesn't
occur in the civil calendar. Rather than trying to have the program swap available choices on the fly,
we decided to allow users select the year 0, and have the program display this as 1 BC, which is
mathematically correct.
Robustness
Now committed to producing a tool for use in the schools, we realized that we need to make the program
extremely fault tolerant. We wanted it to survive as many adverse conditions as possible, because
its value in the classroom would be severely limited if it crashed in the middle of a lesson plan.
Customization
One issue that arose was the external links; my son's school, and many others, are justifiably
leery of the Internet, and have installed programs to block access to any but approved sites.
Our links are stored in a simple text file, which the school may edit to meet its needs. This
also allows for tailoring the links to a particular lesson plan. The same approach was used with
the Help files. These are also flat text files, which may be edited as desired. There is a separate
file for each Help item, which allows the program to download only the items requested, improving
response.
Testing
Moon Calendar was developed in a top-down fashion: first the user interface components, followed
by integration testing of the various pieces, and finally the calendrical and lunar calculation
engines. At each stage, components were rigorously tested before proceeding to the next step. This
sped up the development cycle enormously; bugs were detected and fixed at an early stage, before
their effects could percolate through the entire system, a situation guaranteed to create
headaches trying to figure out where problems arise.
User Response
The user interface was tested at each step with the help of the neighborhood kid's; this was important,
and led to several modifications along the way. Our first "live" test, in an elementary school science
class, was greeted with enthusiasm, and word seems to be spreading; quite a few teachers around the
country have written to say they are using it, and have sent many helpful comments. It seems that the
favorite activity is to see what phase the Moon was in the day you were born, followed by printing
out the calendar for the current month and displaying it in class (this requires a screen dump at
present, due to Java's lack of printing facilities).