← Previous → Next Contents

Design notes

Principles

• Portability
  • The scope is all "reasonably modern" flavors of Unix, X11, and C++
  • Limit language features to those that reliably compile
  • Respect the holy mantra "./configure; make; make install"
  • Allow trivial workarounds for platform- and distribution-specific bugs or special requirements
  • Disallow nontrivial workarounds and those that conflict with correct operation on non-broken platforms
• Availability
  • Limit dependencies on external tools and libraries to those that are typically pre-installed
• Usability
  • Maximize orthogonality of settings and switches
  • Support both interactive and non-interactive use
  • Command-line switches should be no more than two characters long
• Maintainability
  • Accept no bogus patches
  • Maximize orthogonality of modules
• Stability
  • Accept no bogus patches
  • Use no unstable tools or libraries
  • If it ain't broke, don't fix it
  • If it damages usability or maintainability, it's considered broke
  • Do not merely deprecate that which deserves to be deleted

Some noteworthy violations:

• Nontrivial workaround for platforms with obsolete zoneinfo databases
• The –ns switch is deprecated but deserves to be deleted
• libtcd painstakingly purged of bogosity

Harmonics files

XTide has a long history of harmonics file woes and has been through four different file formats trying to solve them.

XTide 1 used a nice, human-readable text format (harmonics.txt) but it was neither efficient nor extensible.  New fields that were really, really necessary got wedged in as "hot comments," initiating a long downhill slide into architectural chaos.

Unwisely, XTide 2 perpetuated the harmonics.txt format but added a new, extensible XML format for subordinate stations only (offsets.xml).  It was anticipated that one of two things would eventually happen:  either a reasonably functional and stable SQL database would become standard issue with the average Unix, obviating the need to avoid that external dependency, or harmonics.txt would go away and all stations would be done in extensible XML.  Neither one happened.  Migration to XML was put off repeatedly because it would exacerbate the performance bottleneck.

Everybody suffered with the lousy performance until Jan Depner proposed to implement a binary format (TCD).  TCD1 fixed the performance problem but the extensibility problem persisted.  New fields could be added with just minor changes to libtcd, but then you needed to recompile the world.  Old versions of XTide couldn't read new harmonics files after fields were added.  This had a major chilling effect on all development that would have required new fields.

TCD2 (a major, incompatible revision) emptied the queue of incompatible changes but also added a field whose content is extension fields encoded as text.  Adding fields this way is not as efficient as adding new binary fields, but it avoids the need to make an incompatible revision over small stuff.  The option to add new binary fields and bump the major rev remains open should that become necessary.

Known problems

Lots of serious design problems were fixed in refactorings begining with version 2.7 (early 2004) and continuing through version 2.9.  Remaining minor problems:

1. The interface with X11 is still weird, especially bootstrapping.
2. The analog tide clock icon caused more problems (with buggy window managers) than it was worth.
3. URLs assigned to prediction pages by the web server should probably be based on the harmonics file name and the location name rather than a transient "row ID."
4. Constituent inference was patched in via libtcd and maybe could have been integrated better.  In theory, you might want to control it on a station-by-station basis like preferred units, and it probably should not require a station reload to turn it on or off.
5. Graph and calendar modes are implemented by transient classes.  These are not proper objects, but they are too complicated to be implemented with methods alone.

C++ feature footprint

At the time XTide 2 was developed, the fancier features of C++ such as the Standard Template Library (STL) and exceptions did not work in a portable fashion among the commonly available compilers, so their use was avoided.  Similarly, Qt and other free alternatives to Motif were not widely available, so Athena Widgets were used.  The resulting interface may seem primitive by today's standards, but it still works.

By the time of the 2.7 refactorings, the STL appeared to be stable and widely available, so standard templates were introduced where appropriate to simplify new code.  Old code was not STLified until the Great Cleanup of 2006 (XTide 2.9).

The long long int data type was introduced in XTide 2.6 as part of the changes to handle dates before 1970 and after 2037.  Nobody complained.

Streams were expunged from XTide 2.6 after compilers started deprecating XTide's use of them.  In XTide, C++ streams did not add value versus plain old C I/O, but this is not the case for every application.

The bool data type was introduced in XTide 2.9.

Exceptions are still not used, but probably could be, as those compilers that don't support them don't support the Standard Template Library either.

Coding conventions

A uniform coding convetion was imposed in XTide 2.9.  See the file CodingConventions.txt included in the distribution tarball.

← Previous → Next Contents