← Previous → Next Contents

Sunset over the bar, Bar Harbor, Maine, 1997-06-24

Design notes

Principles

As originally codified:

As it happened:

Harmonics files

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

ReadableExtensibleEfficientAvailable
TXTXX
XMLXX
SQLXX
TCD1XX
TCD2XXX

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.

Unfortunately, as I forget who once observed, "The worst enemy of the great is the barely good enough."  Among the downstream user community, the obsolete and hopeless .txt and .xml formats refuse to die.

Known problems

Consensus is that the XTide source code does a miserable job of separating the user interfaces from the reusable tide-prediction logic.  As of XTide 2.14 the common files have at least been bundled into a library that can be built upon without making too much of a mess.  However, the XML parser still protrudes into the global namespace, conflicting with any other lex/yacc type parser that the app might want to link with.

Lots of serious design problems were fixed in refactorings beginning 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.
  6. libtcd doesn't let you know whether you are looking at a tide station or a current station until after you load it.
  7. The mechanism that XTide 2.13 and later use to get client side fonts for use in tide graphs is an abomination.
  8. Calendar mode needs an "extended subset" of the settings that every other mode uses.
  9. Application-specific error messages don't belong in libxtide.
  10. Graph mode is a bottomless source of requests for more settings to customize it.

C++ feature footprint and its evolution

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.  C++11 extended initializer lists were used in new code in XTide 2.13, but made optional in XTide 2.13.1 because of continued non-support in Visual Studio 2012.

Exceptions are still not used, but should be.  The bounds-checking operation[] of SafeArray should be replaced with the now-standard at() function.

With "= delete" and nullptr being introduced in XTide 2.15.4 and 2.15.5 respectively, C++11 is now lingua franca but renovation will be piecemeal, as needed.

Coding conventions

A uniform coding convention was imposed in XTide 2.9 (year 2006).  It is now problematically obsolete.  See the file CodingConventions.txt included in the distribution tarball.

Paths not taken

← Previous → Next Contents