Rant: Date and Time fall short of simplicity in D

[Jonathan M Davis]

On Friday, March 29, 2013 06:42:41 Andrej Mitrovic wrote:
> Why was this inconsistency introduced?

The main problem with TickDuration is that it was written by SHOO rather than 
by me and was adjusted to fit into core.time rather than being part of the 
original design. I've made some improvements over time, but I think that the 
overall situation with TickDuration is less than ideal. And honestly, if I 
were to go back, I'd probably get rid of it entirely. I don't see much benefit 
in keeping the time in system ticks (like TickDuration does) rather than 
hnsecs (like Duration does), particularly when the system ticks are often less 
precise than hnsecs anyway (and testing TickDuration is a royal pain).

If I could, I'd probably have a type specifically for dealing with the 
monotonic clock (like TickDuration is used for now), but for stuff like 
StopWatch, I'd just use Duration. But I don't know how much can be done to 
improve the TickDuration situation at this point without breaking code. I 
totally agree that it could use some improvements though.

> I've seen this type of property documentation copied everywhere in
> date/time-related structures and classes, it's not clear from the
> documentation that these are setters, they should be documented as
> such.

I'm sure that improvements can be made, but no one has pointed out much other 
than the fact that the docs are unwieldy with them all being on one page, so I 
haven't had specific suggestions as to sections that should be rewritten or 
anything like that.

> Another example, I once had to convert a long type which represented
> Unix time into DateTime. Here's the code to do it:
> 
> return cast(DateTime)SysTime(unixTimeToStdTime(cast(int)d.when.time));
> 
> It's unbelievable how ugly this is, and it took me way over half an
> hour searching the docs and trying various stuff out to figure this
> out.

Well, on some level, dealing with unix time _should_ be ugly, because you 
shouldn't be doing it normally (though obviously you're forced to sometimes), 
but it is the way it is mainly because making dealing with unix time super 
simple and clean was never really a goal. But the situation could certainly be 
improved. I wouldn't provide a way to convert time_t to a DateTime, since 
DateTime has nothing to do with the system time, and you need a way to control 
what time zone you're converting to, but it's certainly not out of the 
question to provide a function for converting directly from a time_t to a 
system. So, you could get something like

return to!DateTime(unixTimeToSysTime(d.when.time));

which is at least somewhat better.

> Anyway, maybe time and datetime are power-houses in Druntime and
> Phobos, but they trade their features for simplicity.

I don't think that it's really all that complicate ultimately - or at least 
most of the parts are quite simple and straightforward - but there are a lot 
of parts to it, and the way the documentation is laid out makes it difficult to 
figure it out. And that's ultimately the biggest problem with it IMHO.

> Perhaps the real problem is the documentation, or the actual layout of
> the API itself. The API seems to contain a ton of functionality, and
> maybe the more specialized functions should be moved into separate
> modules (and make datetime be part of its own package).
> 
> The docs for std.datetime for example are huge.

I think that the main problem is that it's all sitting in one page with a 
bunch of useless links at the top. It's a great example of a place that ddoc 
does _not_ shine. The ddox version is much better:

http://vibed.org/temp/d-programming-language.org/phobos/std/datetime.html

What I'd really like to do though is to split std.datetime into a package with 
several modules in it where importing std.datetime imports all of them, but 
that requires implementing some variant of DIP 15 or 16. With something like 
that implemented though, I'd jump at the chance to split it up. It really 
should have been split up in the first place, but there was resistance to that 
when I originally presented it as split (probably to a great extent because my 
initial split for it was very bad, and the design evolved quite a bit after 
that; I have a much better idea of how to split it cleanly now), so it 
unfortunately ended up being merged in as one module.

If I were to go back in time, I'd probably split it up and then have it 
reviewed in pieces rather than all together so that each piece got reviewed 
better. On the whole, I think that what's there is quite solid (assuming that 
you can figure out what's there in spite of the documentation issues), but 
there are a few things that could have been done better (e.g. range support, 
which I'd still like to try and improve at least somewhat one of these days), 
and ultimately, I think that it was too much to review at once. But it was the 
first module to go through the review process, so we didn't have any experience 
with it at the time. It _did_ improve quite a bit through the review process 
though, and I do think that it's a good example of how the review process can 
help to improve code before it goes into Phobos, even if the end result isn't 
perfect.

- Jonathan M Davis