Re: [boost] Re: reminder about Date/Time formal review

From: William E. Kempf (williamkempf_at_[hidden])
Date: 2002-04-23 13:58:02

(I sent this once before, but it doesn't appear to have been received.  If
I'm wrong, I'm sorry for the double post.)

First, I vote to accept.  I think there are some serious issues with a few
things as they stand now, but all of these issues can be addressed either
before the first release, or sometime in the near future.  In the mean time,
the library fills a very big void, and does so in a fairly simple,
extendable and generic manner.

Issues I find with the library that should be addressed at some point:

1.  Documentation needs to be made "static".  There is too much of the
documentation that resides on the Wiki, and I'm not sure any of it should be
there.  Such documentation is unusable in an "offline" manner, which is how
most (all?) documentation should be used.

2.  The generic "infrastructure" code found in the gdtl namespace needs
documentation.  This is the core of the library, and probably the most
important piece.

3.  The Gregorian calendar system needs more documentation.  The Gregorian
calendar isn't a simple system, and there are a lot of things not documented
about GDTL's implementation of this system.  For example, historical dates
in a Gregorian system are dependent not only on the date, but also on the
location.  To clarify, different geographical locations adopted the
Gregorian system at different times, and this effects historical dates.  The
two most common "change over dates" used in gregorian date algorithms are
Oct. 4, 1582 and Sept. 14, 1752.  I think it's important to document which
"change over date" is used, since date projections before this date are not
accurate.

(Trivia related to the above:  Did you know that Sept. 2, 1752 was followed
by Sept. 14, 1752?  Or that George Washington's birthday, which we give
today as Feb. 22, 1732 was recorded on that day as Feb. 11, 1731?  Gotta
love this date stuff, no?)

4.  The string conversion and parsing routines should simply be removed.
Instead, we should have iostream capabilities for the various date systems
which obey the locale.  This is, after all, a C++ library and not a Java
library.

5.  I still disagree about the presence of a "universal representation" and
the ability to convert to/from this representation and a particular time
system.  I believe the precision issues to be no more important then the
loss of precision that can occur when converting to/from the various numeric
representations, and that so long as the precision is documented for a given
system it's possible for the user to deal with any loss.  That's something
that's their responsibility.  As for the vagaries of the various political
factors of many time systems... documentation will again save the day in
most cases.  Historical artifacts can be addressed in the time system, while
future variations, such as leap seconds, are simply documented as being
possibly innacurate.  The programmer takes full responsibility when creating
such future dates in the first place, so innacurate conversions to a
universal system causes no more grief then what was already present in the
representation any way.

I do not agree, however, that this "universal representation" should include
mathematical capabilities, as others have argued.  Adding such capabilities
to the universal representation causes choices to be made about the
representation and its resolution and precision that should be made instead
in the specific time systems.

Politics and local conventions can make date/time handling routines
difficult.  But they should not prevent the conversion of dates in one
system into dates in another system, and with an extendable framework where
the time systems available is open ended, the only possible solution is to
provide conversions to/from a "universal representation".  Failing to
include this seems to gaurantee nothing but trouble in the future.

6.  <personal opinion>I don't care for the doxygen documentation.  I believe
in the concept of keeping the documentation in the code, but I think there
are issues with the Doxygen generated documentation that will make it
problematic for Boost (such as the size of generated documentation), and as
someone else pointed out most of the technical documentation currently can
only be found in the Doxygen generated documentation.  I think this will
cause nothing but trouble for Boost users.</personal opinion>

7.  There's a lot of need for more time systems, but this fact should not
prevent the inclusion of GDTL today.

Bill Kempf