DIP 1019--Named Arguments Lite--Final Review

[Olivier FAURE]

On Monday, 26 August 2019 at 23:36:22 UTC, Jonathan M Davis wrote:
> I get the impression that many people just want to use Flag or 
> named arguments as an excuse to avoid even reading the 
> function's documentation. I agree that it's great if what a 
> function call does is obvious at a glance, but I also think 
> that it's dangerous to assume that you know just by looking at 
> the function call. If you don't actually read the function's 
> documentation, then it's easy to end up making bad assumptions 
> about what it does.
>
> Naming is important and having the function's name be 
> representative of what it does makes it far easier to remember 
> what it's supposed to do, and it does help see what code 
> probably does at a glance when you haven't read the docs yet, 
> but ultimately, you need to read the docs, [...] Once you've 
> actually read the docs and are familiar with what the functions 
> do, then the names serve to remind you rather than inform you, 
> and the need to label everything is far less. But for a lot of 
> arguments, you have the names of the variables being passed 
> anyway, and if anyone really wants to label what a boolean 
> literal is for, they can always use a comment in-place.

I'm mostly neutral on named parameters (they're nice to have), 
but I'm not sure I agree with the reasoning here.

In theory, it would be nice to always refer to documentation 
before using a function. In practice, in most of my jobs so far, 
I have almost never done so except when working with an external 
library, for good reasons:

- I don't want to use an IDE (Atom's multi-cursor support is a 
core part of my workflow, among other things), which means I 
don't have documentation-as-hover-text yet.

- I'm often asked to make a 2-lines change in a 60-lines 
function, and reading the documentation for each function call is 
simply not an efficient way to do that. I need to be able to 
locate the parts relevant to my task quickly, and informative 
names help me *a lot*.

- For most of the code I work on, the documentation looks like 
this:

     /**
     *** This method is used to set visible or invisible the 
HopPoints.
     **/
     void makeHopPointVisible(bool i_hopPointVisible);

eg, it paraphrases what the prototype already says.

Now, documentation is important and valuable, and I do read it 
when I'm eg rewriting a function. But having code that can be 
understood at a glance without looking at its source/doc is also 
valuable, and I think this value far outweighs the moral hazard 
of occasional bikeshedding or of people skipping documentation.

(the above goes triple for developers with accessibility issues, 
eg blind devs using text-to-speech to browse code)