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

[Haravikk]

> 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. 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160128/ed357510/attachment.html>