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

[David Owens II]

> 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.

>> So the question is this though: what is the better Swift API? I think
>> examples like these and reasons as to why one is chosen over the other
>> at least help with the guidelines being more inclusive. 
> 
> Yeah, the rationales that led to the guidelines specifying #2 may be
> hard to appreciate.  I'm going to lay them out here so we can talk about
> whether and how to incorporate them in the document (assuming that the
> guidelines' ruling on that API won't change):
> 
> * Simple guidelines are better than complex guidelines.
> 
> * Guidelines with exceptions and special cases are more complex.
> 
> * We don't have a clear rule for deciding that one API needs/doesn't
>  need a first argument label.
> 
> * Even if we come up with such a rule, if it can't be *automated* in the
>  importer, Cocoa will fail to follow the guideline in Swift.  So for
>  any rule that considers high-level concepts like the “semantic
>  connection between parameters,” there needs to at least be a heuristic
>  that manages to approximate it when applied to Cocoa APIs.
> 
> * If we say “do it where it makes sense,” programmers will waste
>  countless hours arguing about whether it makes sense in a given case.
>  One great value of API guidelines is that they prevent that kind of
>  rat-holing.

Heh... I think this is where more examples in the guidelines helps. =)

Related: https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007874.html <https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007874.html>

-David

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/b2f8fa91/attachment.html>