Programming Windows D Examples are now Online!

[Steven Schveighoffer]

On Thu, 23 Jun 2011 18:42:45 -0400, Jonathan M Davis <jmdavisProg at gmx.com>  
wrote:

> On 2011-06-23 15:10, Steven Schveighoffer wrote:
>> On Thu, 23 Jun 2011 18:02:02 -0400, Jonathan M Davis  
>> <jmdavisProg at gmx.com>
>>
>> wrote:
>> > On 2011-06-23 14:50, Andrej Mitrovic wrote:
>> >> On 6/23/11, Steven Schveighoffer <schveiguy at yahoo.com> wrote:
>> >> > On Thu, 23 Jun 2011 07:27:34 -0400, Jimmy Cao <jcao219 at gmail.com>
>> >>
>> >> wrote:
>> >> >> Thread.sleep( 70_000_000 ); // 7 sec
>> >> >
>> >> > Gah!
>> >> >
>> >> > Here, let me fix that for you:
>> >> >
>> >> > Thread.sleep(dur!"seconds"(7));
>> >> >
>> >> > :)
>> >> >
>> >> > -Steve
>> >>
>> >> I find it very odd that for seconds we use "seconds", but for
>> >> everything else we use "msec", "usec", "hnsecs" abbreviations.
>> >
>> > Because it makes sense to use the full names up to seconds. After  
>> that,
>> > they're too long, so they get abbreviated.
>>
>> You could argue that mseconds is not much longer than seconds. It's  
>> still
>> an abbreviation.
>>
>> You could also argue that seconds is too long, couldn't it be secs? One
>> thing that sucks about having inconsistent abbreviations, I have to look
>> them up, even when I know what I'm typing makes sense to a reader, it  
>> just
>> may not be what the function expects. For instance, before I sent this
>> message, I had to look it up to make sure it was valid.
>
> Unfortunately, there are so many variations on what they could be that  
> there's
> no way to make them so that everyone is going to remember them  
> correctly. So,
> no matter what I picked, someone would have been unhapy with it.

Right.  I totally agree, if you have to have one, you just have to choose  
and be done with it.  The only reason we can have this conversation is  
because it's really easy to just add another "overload". :)

>> But here's an idea -- milliseconds, msecs, and mseconds could all map to
>> the same template function.
>>
>> hectonanoseconds, hm.. that's a long one :)
>
> I thought about doing that (though it _never_ occurred to me to use  
> mseconds,
> since that feels to me like you abbreviated half of it, which is just  
> weird to
> me). The problem is that that feels a bit too much like the inconsistent
> horror that is html where it accepts just about anything. I generally  
> prefer
> things to be strict and consistent over trying to guess what was meant.  
> It
> also makes the template constraints uglier. I'm not completely against  
> the
> idea, but I'm not convinced that it's a good one either.

I'm not completely for it either, it was just a thought.  Personally, I  
think super-abbreviated and fully-spelled-out would be the two best  
options to have.  Since you are already sticking it in a namespace (dur),  
it should be rather obvious what each is:

hns or hectonanoseconds
us or microseconds
ms or milliseconds
s or seconds
m or minutes
h or hours
d or days
w or weeks
mo or months (yeah, this one is sucky)
y or years

>
> As it stands, all units seconds and greater are completely  
> unabbreviated, and
> all of the sub-second units are abbreviated, which if you're going to
> abbreviate some but not all feels very consistent to me (though again,  
> what
> seems perfectly logical to one person may not seem that way to another).

It would be good to highlight this pattern in the documentation.  It makes  
it easier to remember which ones are abbreviated!

> I
> _don't_ want to change them to something else at this point. There's  
> enough in
> core.time and std.datetime to get used to already, and that's a pretty
> heavily-used feature in those modules. It _might_ be worth making it so  
> that
> other variants of the units' names work, but I'm not convinced that  
> being lax
> about it is necessarily a good idea.

To me, an optimal API is one you don't have to look up.  It just makes  
sense.  There are various ways to achieve this, and it's probably  
achievable with your scheme as long as you give an easy rule to remember  
(i.e. subseconds are abbreviated, everything else is not).

One thing that would be good to have is to have a more defined error  
message when you type the wrong term.  i.e.:

Error: millis is not a valid unit, try hnsecs, usecs, msecs, ...

-Steve