One of the stumbling blocks on using std.datetime is how
many bizarre abbreviations it has.

auto time = Clock.currentTime(); // bzzt, wrong

if(time - something > duration!"hours"(4)) // bzzt, wrong

writeln(time.toISOExtendedString()); // bzzt, wrong, but this used to work!



Why aren't we using real words here? Real words are easier
to remember and easier to type.


This is almost as bad as "creat" and "umount". It's like
these names are deliberately designed to fail your
first guess. Our minds are pretty good at remembering
words and sentences; it is an existing database in there
that follow established patterns.

Arbitrary abbreviations only work through special-cased
brute force rote memorization.


And the dmd spellchecker doesn't always help:

Error: template instance duration!("hours") template 'duration' is not defined, did you mean Duration?


Nope, apparently, I meant "dur". Ridiculous.



std.datetime isn't the only one that does this, of course.
rndGen() in the middle of sane names like "unpredictableSeed"
and "randomShuffle". There's more, too.





Some abbreviations are justified by precedent. rmdir() has
been around for a long time, so we know what it is. Stringz
is similarly classic. "printf" is one of the earliest words
many of us saw as programmers.

But "dur"? "curr"?


What the hell? Can we please stop this?

On 06-03-2012 17:38, Adam D. Ruppe wrote:
> One of the stumbling blocks on using std.datetime is how
> many bizarre abbreviations it has.
>
> auto time = Clock.currentTime(); // bzzt, wrong
>
> if(time - something > duration!"hours"(4)) // bzzt, wrong
>
> writeln(time.toISOExtendedString()); // bzzt, wrong, but this used to work!
>
>

There's also core.time.TickDuration.currSystemTick() which really ought to be currentSystemTicks.

>
> Why aren't we using real words here? Real words are easier
> to remember and easier to type.
>

+1.

>
> This is almost as bad as "creat" and "umount". It's like
> these names are deliberately designed to fail your
> first guess. Our minds are pretty good at remembering
> words and sentences; it is an existing database in there
> that follow established patterns.
>
> Arbitrary abbreviations only work through special-cased
> brute force rote memorization.
>
>
> And the dmd spellchecker doesn't always help:
>
> Error: template instance duration!("hours") template 'duration' is not
> defined, did you mean Duration?
>
>
> Nope, apparently, I meant "dur". Ridiculous.
>
>
>
> std.datetime isn't the only one that does this, of course.
> rndGen() in the middle of sane names like "unpredictableSeed"
> and "randomShuffle". There's more, too.
>
>
>
>
>
> Some abbreviations are justified by precedent. rmdir() has
> been around for a long time, so we know what it is. Stringz
> is similarly classic. "printf" is one of the earliest words
> many of us saw as programmers.
>
> But "dur"? "curr"?
>
>
> What the hell? Can we please stop this?

I agree entirely. Phobos (and druntime) needs to follow the same convention the .NET Framework does: Always use whole words, and only abbreviate if the abbreviation is universally well-known.

-- 
- Alex

I'll never forgive std.datetime for this mistake:

auto sw = StopWatch(AutoStart.yes);
writeln(sw.peek.hnsecs);
writeln(sw.peek.nsecs);
writeln(sw.peek.usecs);
writeln(sw.peek.msecs);
writeln(sw.peek.secs);  // bzzzzz NOPE
writeln(sw.peek.seconds);

I misspell this thing every single time I use stopwatch to count seconds.

On 06.03.2012 21:09, Andrej Mitrovic wrote:
> I'll never forgive std.datetime for this mistake:
>
> auto sw = StopWatch(AutoStart.yes);
> writeln(sw.peek.hnsecs);
> writeln(sw.peek.nsecs);
> writeln(sw.peek.usecs);
> writeln(sw.peek.msecs);
> writeln(sw.peek.secs);  // bzzzzz NOPE
> writeln(sw.peek.seconds);
>
> I misspell this thing every single time I use stopwatch to count seconds.

Me too.
It's coming from separate stopwatch module that got merged with std.datetime, so the blame is somewhat misplaced :)

-- 
Dmitry Olshansky

On 3/6/12, Dmitry Olshansky <dmitry.olsh@gmail.com> wrote:
> It's coming from separate stopwatch module that got merged with std.datetime, so the blame is somewhat misplaced :)

I've argued about it with the current DateTime Czar, so it's not really missplaced. :)

On Tue, Mar 06, 2012 at 05:38:09PM +0100, Adam D. Ruppe wrote:
> One of the stumbling blocks on using std.datetime is how many bizarre abbreviations it has.
> 
> auto time = Clock.currentTime(); // bzzt, wrong
> 
> if(time - something > duration!"hours"(4)) // bzzt, wrong
> 
> writeln(time.toISOExtendedString()); // bzzt, wrong, but this used
> to work!
> 
> 
> 
> Why aren't we using real words here? Real words are easier to remember and easier to type.
[...]

I have to disagree on this one. One of the reasons I hate Java so much is because of its gratuitouslyOverlongFullySpelledOutVariableNames. I mean, it takes almost the entire line of code to just refer to a variable, let alone do anything useful with it. There's nothing wrong with using abbreviations... BUT they have to be *consistent*.

I do agree with you that arbitrary abbreviations are very bad. One module abbreviates "current" as "cur" and another module uses "curr". I agree that's very bad. We do need to standardize on these things so that they are consistent.

My stance is that variable names *should* be abbreviated, but within reason, and abbreviations must be *consistent*.  Shortening loop indices to i, j, k is OK, because we know what they mean. However, renaming, say, "hours" to "i" is bad. On the other hand, spelling out "dayOfTheMonthExceptInLeapYears" is bad too. There needs to be a balance. Which is where consistency comes in, because if "balance" means "arbitrary point between two extremes", that doesn't work either.

The sec/seconds arbitrary switch as somebody pointed out is an example of inconsistency. It causes confusion and makes it hard to remember. But if seconds was *always* abbreviated "sec", then there's no problem at all, and it's easier to type too.

IOW I don't think abbreviations would be that big an issue if it weren't for the inconsistency. The fault is with inconsistency, not with abbreviations.


T

-- 
Life would be easier if I had the source code. -- YHL

On 06-03-2012 19:08, H. S. Teoh wrote:
> On Tue, Mar 06, 2012 at 05:38:09PM +0100, Adam D. Ruppe wrote:
>> One of the stumbling blocks on using std.datetime is how
>> many bizarre abbreviations it has.
>>
>> auto time = Clock.currentTime(); // bzzt, wrong
>>
>> if(time - something>  duration!"hours"(4)) // bzzt, wrong
>>
>> writeln(time.toISOExtendedString()); // bzzt, wrong, but this used
>> to work!
>>
>>
>>
>> Why aren't we using real words here? Real words are easier
>> to remember and easier to type.
> [...]
>
> I have to disagree on this one. One of the reasons I hate Java so much
> is because of its gratuitouslyOverlongFullySpelledOutVariableNames. I
> mean, it takes almost the entire line of code to just refer to a
> variable, let alone do anything useful with it. There's nothing wrong
> with using abbreviations... BUT they have to be *consistent*.
>
> I do agree with you that arbitrary abbreviations are very bad. One
> module abbreviates "current" as "cur" and another module uses "curr". I
> agree that's very bad. We do need to standardize on these things so that
> they are consistent.
>
> My stance is that variable names *should* be abbreviated, but within
> reason, and abbreviations must be *consistent*.  Shortening loop indices
> to i, j, k is OK, because we know what they mean. However, renaming,
> say, "hours" to "i" is bad. On the other hand, spelling out
> "dayOfTheMonthExceptInLeapYears" is bad too. There needs to be a
> balance. Which is where consistency comes in, because if "balance" means
> "arbitrary point between two extremes", that doesn't work either.
>
> The sec/seconds arbitrary switch as somebody pointed out is an example
> of inconsistency. It causes confusion and makes it hard to remember. But
> if seconds was *always* abbreviated "sec", then there's no problem at
> all, and it's easier to type too.
>
> IOW I don't think abbreviations would be that big an issue if it weren't
> for the inconsistency. The fault is with inconsistency, not with
> abbreviations.
>
>
> T
>

You're arguing about variable names while the original post was about function names. IMHO you should not conflate naming of these two; the former is about locally scoped symbols while the latter is about publicly exposed APIs.

(Also, seriously, I think you're over-dramatizing the Java variable naming thing; I rarely see names that are as bad as you claim...)

-- 
- Alex

Le 06/03/2012 19:08, H. S. Teoh a écrit :
> On Tue, Mar 06, 2012 at 05:38:09PM +0100, Adam D. Ruppe wrote:
>> One of the stumbling blocks on using std.datetime is how
>> many bizarre abbreviations it has.
>>
>> auto time = Clock.currentTime(); // bzzt, wrong
>>
>> if(time - something>  duration!"hours"(4)) // bzzt, wrong
>>
>> writeln(time.toISOExtendedString()); // bzzt, wrong, but this used
>> to work!
>>
>>
>>
>> Why aren't we using real words here? Real words are easier
>> to remember and easier to type.
> [...]
>
> I have to disagree on this one. One of the reasons I hate Java so much
> is because of its gratuitouslyOverlongFullySpelledOutVariableNames.

Let me stop you just here.

Name come in a context. Hence variable names are in a function, that is in a class, that is in a package, that is in another package, ..., that is in a project.

If you need a very long name to cite something, it doesn't means that it should be abbreviated. It means that it is in the wrong place and you need to refactor.

When you come up with such a variable name, the code is telling you something. « Hey dude, stop here what you do, refactor and put that stuff in a convenient place before continuing ! »

Unfortunately, many dev understands it as « Hey, this name is too long, let use an abbreviation ! ». No you have fucked up variable name in a fucked software architecture.

This happen a lot in java. But remember, 90% of everything is crap.

Le 06/03/2012 18:09, Andrej Mitrovic a écrit :
> I'll never forgive std.datetime for this mistake:
>
> auto sw = StopWatch(AutoStart.yes);
> writeln(sw.peek.hnsecs);
> writeln(sw.peek.nsecs);
> writeln(sw.peek.usecs);
> writeln(sw.peek.msecs);
> writeln(sw.peek.secs);  // bzzzzz NOPE
> writeln(sw.peek.seconds);
>
> I misspell this thing every single time I use stopwatch to count seconds.

I feel less lonely :D But that doesn't solve the problem.

On Tue, Mar 06, 2012 at 07:13:47PM +0100, Alex Rønne Petersen wrote:
> On 06-03-2012 19:08, H. S. Teoh wrote:
> >On Tue, Mar 06, 2012 at 05:38:09PM +0100, Adam D. Ruppe wrote:
> >>One of the stumbling blocks on using std.datetime is how many bizarre abbreviations it has.
> >>
> >>auto time = Clock.currentTime(); // bzzt, wrong
> >>
> >>if(time - something>  duration!"hours"(4)) // bzzt, wrong
> >>
> >>writeln(time.toISOExtendedString()); // bzzt, wrong, but this used
> >>to work!
> >>
> >>
> >>
> >>Why aren't we using real words here? Real words are easier to remember and easier to type.
> >[...]
> >
> >I have to disagree on this one. One of the reasons I hate Java so much is because of its gratuitouslyOverlongFullySpelledOutVariableNames. I mean, it takes almost the entire line of code to just refer to a variable, let alone do anything useful with it. There's nothing wrong with using abbreviations... BUT they have to be *consistent*.
> >
> >I do agree with you that arbitrary abbreviations are very bad. One module abbreviates "current" as "cur" and another module uses "curr". I agree that's very bad. We do need to standardize on these things so that they are consistent.
> >
> >My stance is that variable names *should* be abbreviated, but within reason, and abbreviations must be *consistent*.  Shortening loop indices to i, j, k is OK, because we know what they mean. However, renaming, say, "hours" to "i" is bad. On the other hand, spelling out "dayOfTheMonthExceptInLeapYears" is bad too. There needs to be a balance. Which is where consistency comes in, because if "balance" means "arbitrary point between two extremes", that doesn't work either.
> >
> >The sec/seconds arbitrary switch as somebody pointed out is an example of inconsistency. It causes confusion and makes it hard to remember. But if seconds was *always* abbreviated "sec", then there's no problem at all, and it's easier to type too.
> >
> >IOW I don't think abbreviations would be that big an issue if it weren't for the inconsistency. The fault is with inconsistency, not with abbreviations.
> >
> >
> >T
> >
> 
> You're arguing about variable names while the original post was about function names. IMHO you should not conflate naming of these two; the former is about locally scoped symbols while the latter is about publicly exposed APIs.

The same rule applies. Function names should not be overly long, especially if they are limited in scope (say, class methods). The general rule is that the wider the scope of a name, the more unambiguous it needs to be. (And unambiguous doesn't necessarily mean longer.)

Anyway, names like Clock.currentTime() are too long, IMO. There's nothing wrong with shortening it. But the abbreviations need to be consistent, so it shouldn't be currTime in one case, and curYear in another case. And consistency needs to be across the board.


> (Also, seriously, I think you're over-dramatizing the Java variable naming thing; I rarely see names that are as bad as you claim...)
[...]

OK, I exaggerated a little. :-) But my point stands, that I find many of these names just way too long for my tastes. Like BufferedOutputStream. Or ByteArrayOutputStream.  Ugh. I mean, we're writing programs here, not essays. Why spell things out in full if we don't need to?


T

-- 
If you think you are too small to make a difference, try sleeping in a closed room with a mosquito. -- Jan van Steenbergen