[swift-evolution] [Review] SE-0023 API Design Guidelines

[Dave Abrahams]

on Wed Jan 27 2016, David Owens II <swift-evolution at swift.org> wrote:

>> On Jan 26, 2016, at 1:32 PM, Dave Abrahams via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>>>> It all depends on what it does for the doc comment.  IMO there's nothing
>>>> wrong with “Inserts `newElement` before the `i`th element, or at the end
>
>>>> if `i == count`”.
>>> 
>>> Hmm… we disagree on that point. If I need to go the documentation to
>>> get basic clarification of the parameter, I’m not really sure what the
>>> point of the label is then.
>> 
>> I don't understand your point.  The argument label (“at”) appears at the
>> use-site.  The parameter name (“i”) appears only at the declaration
>> site.  I'm saying the name of the parameter should be chosen to make the
>> documentation comment read well.  Are you arguing that it shouldn't?
>> 
>> Or are you arguing that
>> 
>>  /// Inserts `newElement` before the `i`th element, or at the end
>>  /// if `i == count`
>>  mutating func insert(newElement: Iterator.Element, at i: Int)
>> 
>> would read better with a different name in place of `i`?
>
> Yes, if `i` here was `index`, then the API without the full doc
> comment is much more readable. Just seeing the function signature
> really offers no clarity of what the code is supposed to be doing when
> `i` is used. We can guess, but I prefer more explicit over guessing.

? it's in the base name and argument labels, not to mention the types.
All the information available at the use-site, and more, is there in the
declaration.


-- 
-Dave