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

[Radosław Pietruszewski]

_Can we_ say that objectively, though?

I would agree that 

> items.insert(12, atIndex: 2)

reads more _like an English_ sentence than without the “at”. But I would hold back from saying “reads more naturally” / “more fluidly”, because it suggests to me that it’s inherently better. And I’m not sure I agree.

I think there’s an agreement that making Swift sound like English is a non-goal. In fact, trying to do so is often harmful as we end up putting unnecessary words, like “with”, “and”, “by”, etc. (I’m not saying they’re always unnecessary; they often help convey the semantics or intent, or are needed for the method name to make sense. But too often they’re just glue words used to make code sound like English without any actual readability benefits, and merely adding noise.)

Personally, out of:

1. insert(12, at: 2)
2. insert(12, atIndex: 2)
3. insert(12, index: 3)

I like 1 and 2 best. 1) is neat, short, and still understandable in the context of collections. 3) describes the parameter more explicitly, still clear. 2) tries to do both, but it’s really unnecessary. It adds no readability value in my mind over either.

— Radek

> On 25 Jan 2016, at 01:33, David Owens II via swift-evolution <swift-evolution at swift.org> wrote:
> 
> Not quite, I think we can objectively say that this:
> 
> items.insert(12, atIndex: 2)
> 
> Reads far more naturally than this:
> 
> items.insert(12, index: 2)
> 
> In the later, you have to add words to make the API read fluidly. The former simply does by the nature of the words.

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