DIP 1019--Named Arguments Lite--Final Review

[Yuxuan Shui]

On Tuesday, 27 August 2019 at 20:27:13 UTC, Jonathan M Davis 
wrote:
> On Tuesday, August 27, 2019 12:05:25 PM MDT Yuxuan Shui via 
> Digitalmars-d wrote:
>> On Tuesday, 27 August 2019 at 17:39:44 UTC, H. S. Teoh wrote:
>> > On Tue, Aug 27, 2019 at 05:01:21PM +0000, Yuxuan Shui via
>> >
>> > Digitalmars-d wrote:
>> >> On Monday, 26 August 2019 at 21:48:42 UTC, Jonathan M Davis
>> >
>> >> wrote:
>> > [...]
>> >
>> >> > The _only_ use case IMHO where they add any real value is 
>> >> > when you have a long parameter list where most of the 
>> >> > parameters having default arguments.
>> >>
>> >> Disagree. Oftentimes having the name clarifies a function, 
>> >> so the _reader_ doesn't have to read the document to figure 
>> >> out what a function call does
>> >
>> > [...]
>> >
>> > That's exactly Jonathan's point.  The reader *assumes* 
>> > semantics based on the names of the function and parameters.
>>
>> Well at this point you might just as well say the reader 
>> cannot *assume* semantics based on the documentation of the 
>> function either.
>
> There's a world of difference between assuming that what the 
> documentation says is correct and assuming that you understand 
> what a function does correctly based off of its name (and 
> potentially the name of its parameters if named arguments are 
> used). The name of a function should be representative of what 
> it does and make it easier to remember what the function does 
> after you've already read the documentation (the same would be 
> true of parameters if named arguments are in the language), but 
> ultimately, anyone using a function needs to read its 
> documentation rather than assuming what it does based on its 
> name or the name of its arguments. In worse cases, you do have 
> to actually go read the function's source to know what it does, 
> but that just means that the documentation was bad or 
> nonexistent, which is of course undesirable and shouldn't 
> happen (especially in publicly available libraries). We do all 
> unfortunately sometimes have to deal with such situations, but 
> regardless, it's not reasonable to assume what a function does 
> based solely on its name, the name of its parameters, or the 
> names of its arguments. If that's supposed to be one of the 
> main benefits of named arguments, then I think that that's a 
> great reason _not_ to have them.
>
> This sort of issue seems to come up at least some of the time 
> when naming functions or types. Some people seem to think that 
> they should be able to just think of a name and have it exist 
> and act exactly the way they want without looking anything up. 
> Similarly, some people tend to think that when they see a name, 
> they should know exactly what it does based on the name and how 
> it was used without reading the docs. None of that is 
> reasonable IMHO. You always need to read the documentation, 
> because it's frequently the case that a function doesn't work 
> exactly the way you infer that it does, and unless the person 
> who named the function thinks exactly like you do, differences 
> in names and behaviors are bound to pop up. Ultimately, good 
> names help people remember what stuff does (and even help them 
> infer what things probably do before actually reading the 
> docs), but there is no excuse for not reading the documentation 
> (beyond it not existing, in which case, that's on the head of 
> whoever wrote it, and you're potentially going to have to read 
> the source code to get the information you need, which is a 
> whole other problem).

I am not saying having argument names can completely eliminate 
the need to read the documents. But there are cases where the 
function name and parameter names so obviously indicates what the 
function does (e.g. createWindow(height: , width: )), if the 
function actually does something else, it would mean it was 
written terribly.

And there are also cases where you have read the document of the 
function, know what the function does, but cannot remember 
exactly what each of the parameters are for. Having the name of 
the parameters could help tremendously.

>
> - Jonathan M Davis