We need better documentation for functions with ranges and templates

[Chris Wright via Digitalmars-d]

On Tue, 15 Dec 2015 15:55:31 +0000, ZombineDev wrote:

> On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
>>
>> We are talking about a better documentation, not about the C# vs D
>> performance, we already know the winner. Since C# is an OOP-only
>> language, there is only one way to do reflection - using OOP,
>> (voluntarily ignoring the fact that NGen will reduce this call to a
>> simple memory read in case of arrays).
>>
>> Your affirmation:
>>
>>> the docs don't even bother to mention that it is almost always O(n),
>>> because non of the Enumerable extention methods preserve the
>>> underlying ICollection interace
>>
>> was false and you don't need to look to the source code to find out,
>> the Remarks section is self-explanatory:
>>
>> "If the type of source implements ICollection<T>, that implementation
>> is used to obtain the count of elements. Otherwise, this method
>> determines the count."
> 
> Sorry, I do not know how to make this clear:
> 
> NONE OF THE System.Linq.Enumerable EXTENSION METHODS PRESERVE THE
> STRUCTURE (THE INTERFACES THEY IMPLEMENT) OF THE SEQUENCE THEY ARE
> OPERATING ON. DON'T BELIEVE THAT NGEN WILL AUTOMAGICALLY MAKE YOUR CODE
> FASTER. IT WILL NOT. UNICORNS DO NOT EXISTS. AT LEAST THEY DO NOT IN
> .NET OR JAVA. DO NOT BLINDLY BELIEVE. TEST!

    'I said it very loud and clear:
    I went and shouted in his ear.'

Humpty Dumpty raised his voice almost to a scream as he repeated this 
verse, and Alice thought with a shudder, 'I wouldn't have been the 
messenger for anything!'

    'But he was very stiff and proud:
    He said, "You needn't shout so loud!"

    And he was very proud and stiff:
    He said 'I'd go and wake them, if --"'

> See for yourself: https://ideone.com/L5FatQ
> 
> This what I got on my machine:
> 00:00:00.0011011 for N = 1 -> 1, List<int>.Select(..).Count()

You have observed that System.Linq hasn't fully propagated metadata about 
collections through operations where it could and where D's equivalents 
do.

You are blaming this on object oriented programming. It is easy to 
support a handful of extra operations (like O(1) collection length) on 
all System.Linq types with object oriented code. It gets harder as you 
try to support more operations, but there are probably only a few you 
need to worry about.

It is more convenient to use templates and static if, especially as the 
number of operations grows. But it's certainly possible to do in OOP.

You are also explicitly opting out of adaptive optimizations by using 
ngen. That's a much smaller effect, of course. ngen is better for fast 
startup and to guarantee that the runtime won't try to re-JIT your code 
when you're executing code that can't stand for such a pause.

>> - You don't need to understand computer science terms to find out what
>> a function does;
> 
> A major disadvantage, if you ask me :D

"Come learn D, it's actively hostile toward novices!" ...perhaps a 
different marketing campaign would work better.

>> There is no indication what happens if the range contains more than
>> size_t.max elements:
>> - integer overflow;
> 
> Practically impossible on 64-bit and unlikely that someone will use
> walkLength with files on 32-bit. It's called *walk*Length for a reason.

Not all ranges are backed by data in memory or on disk. I could create a 
range over the time from the Big Bang to today in 10-femtosecond 
intervals, for instance. Granted, it would be silly for me to call 
walkLength on that.

Also, there's no indication what the return type is. It could be a short 
for all I know. Maybe the writer accidentally wrote 'auto count = 0;' 
instead of explicitly using size_t, in which case by three billion entry 
range will report that its walk length is negative.

I read the source code and know it's using size_t (and should perhaps 
just be ulong). But it's not documented anywhere.