[swift-evolution] [Review] SE-0005 Better Translation of Objective-C APIs Into Swift

[Dave Abrahams]

on Thu Jan 28 2016, Haravikk <swift-evolution at swift.org> wrote:

>> On 27 Jan 2016, at 22:37, Douglas Gregor
>> <dgregor at apple.com> wrote:
>>> On Jan 27, 2016, at 2:15 PM, Haravikk via swift-evolution
>>> <swift-evolution at swift.org
>>> <mailto:swift-evolution at swift.org>>
>
>>> wrote:
>>> 
>>> I’d like to reiterate that my preference for cases like these would be:
>>> 
>>> 	respond(withData data: Data)
>>> 
>>> This way the action (function name) is still simplified to respond,
>>> but the sentence structure remains for clarity, which I still think
>>> is the best of both worlds.
>> 
>> Observation: I’ve never seen anyone write Swift code this way, with
>> a proposition “with” on the first argument label. Have you?
>
> I do ;)
>
> One thing I really love about Swift’s external names is the ability to
> make my function calls read a lot like natural language, but in doing
> so actually clarify how a parameter is used, potentially eliminating
> the need to consult documentation at all.
>
> Granted “with” may not be the best word, but in the example it implies
> to me more that the data itself is being returned, rather than being
> used to generate some kind of other response, whereas “data” on its
> own might require me to check to be sure I’ve understand what the
> function will do with that data.
>
> For example, I might declare methods like:
>
> 	func find(theSearchTerm needle:String, inTheString haystack:String) -> Range<String.Index>
> 	let match = matcher.find(theSearchTerm: “find me”, inTheString: “see if you can find me in this”)
>
> Still might not be the best example but hopefully it gives you the
> idea. 

Well, this is certainly a style we want the language to allow, but I'm
just as certain it's not what we want the API guidelines to push people
toward...

> Sometimes there’s verbosity for the sake of maintaining the pattern,
> but the idea is to end up with self-documenting function
> declarations. Of course I had SwiftDoc anyway for clarity and because
> I’m an habitual documenter, but if a function can be understood purely
> from how it’s used then that’s a good thing IMO. I should mention I’m
> a huge fan of Applescript’s syntax (though I hate its performance).
>
> Of course I realise we’re talking about converting Objective-C
> functions, but while I don’t like the overly long function names (I
> prefer functions with a similar action to have the same name) I do
> like that some of them are self-documenting thanks to the added
> verbosity, and I’m just concerned that we might lose some of that, as
> personally I try to keep my functions fairly descriptive in my own
> code.

...and the goal is to have the importer emulate conformance to the
guidelines.  But regarding your concern about clarity, do you feel the
prose you wrote above is unclear?  I notice you didn't write

  I’m just [a feeling]: concerned that [the subject of that feeling]: we
  might [a consequence]: lose [the object of that consequence]: some of
  that.

To me, that seems analogous to 

   find(theSearchTerm: x)

-- 
-Dave