Please do not use 'auto' return types without thoroughly describing the interface

Piotr Klos poliklosio at happypizza.com
Tue Dec 26 12:38:57 UTC 2017


On Monday, 25 December 2017 at 22:48:39 UTC, H. S. Teoh wrote:
> On Mon, Dec 25, 2017 at 04:26:52PM +0000, Piotr Klos via 
> Digitalmars-d wrote:
>> On Monday, 25 December 2017 at 03:23:33 UTC, Neia Neutuladh 
>> wrote:
>> > If you have a function with a return type listed as `auto`, 
>> > please thoroughly describe what interface the return value 
>> > provides.
>> > 
>> 
>> I would just like to say that I strongly agree. Lack of 
>> documentation of template parameters and other unspecified 
>> types in interfaces, like auto return types is one of the 
>> primary reasons for people to turn away from template 
>> libraries and regard templates as obscure.
>
> While I agree that all template parameters ought to be 
> documented and all auto return types thoroughly described, I 
> disagree with explicit naming of auto return types. The whole 
> point of auto return types is to return an *opaque* type that 
> user code should not depend on, apart from what the 
> documentation says you can do with the type.  It's a matter of 
> encapsulation, i.e., "you can do X, Y, Z with the return value 
> of this function, everything else is none of your business". 
> Or, in other words, if your code can't possibly work without 
> (...)

While I agree with the sentiment that encapsulation is good and 
all, I think the emphasis is on the wrong thing here. It seems 
that you are happy to take forever thinking about the right thing 
to do, even at the price of eternal unusability. The desing goals 
of standard library should be the exact opposite, i.e. make 
things 100% usable even at the cost of making less features, and 
then maybe later make more features if a need appears.
If something is not usable yet, it shouldn't be in the stdlib!

So in my humble opinion the process for getting something into a 
stdlib should be create + document + assess usability -> repeat 
-> publish or reject, not create -> publish -> document, 
especially for template libs!
Otherwise you risk that the lib won't be very usable after all 
despite the best intentions (if users are even patient enouh to 
wait for the proper docs). For example look at all the template 
parameters in boost c++ libraries, most of which are never used.


More information about the Digitalmars-d mailing list