This issue was discussed at some length during review of SE-0023. As you know, the guidelines themselves offer three admonitions:
[1] Include all the words needed to avoid ambiguity for a person reading code where the name is used. For example, consider a method that removes the element at a given position within a collection.
// ... employees.remove(at: x)If we were to omit the word
atfrom the method signature, it could imply to the reader that the method searches for and removes an element equal tox, rather than usingxto indicate the position of the element to remove.[2] Omit needless words. ... In particular, omit words that merely repeat type information.
// ... allViews.removeElement(cancelButton)In this case, the word
Elementadds nothing salient at the call site. ...[3] Compensate for weak type information to clarify a parameter’s role. Especially when a parameter type is
NSObject,Any,AnyObject, or a fundamental type suchIntorString, type information and context at the point of use may not fully convey intent. ...func add(_ observer: NSObject, for keyPath: String) // ... vagueTo restore clarity, precede each weakly typed parameter with a noun describing its role:
func addObserver(_ observer: NSObject, forKeyPath keyPath: String) // ... clear
Given these guidelines, the following question was asked during review of SE-0023:
Many of the ObjC APIs will come across with prepositions in the external labels, such as:
func insert(_ anObject: AnyObject, atIndex index: Int)... when we look at the various API options in front of us when designing new APIs, do we use "atIndex", "at", or simply stick with the default "index"? This is where I think the guidelines don't help steer us in any direction.
To which, you replied (with emphasis added by me):
That'll come in as
func insert(_ anObject: AnyObject, at index: Int)... the intent would be to move you toward what I wrote above. ... we could be more explicit about that. I think the admonition to avoid merely repeating type information is the applicable one here, but it really only works to push you away from "index" in the context of an associated Index type, and NSArray doesn't have one.
So to synthesize:
The rules tell us that, ordinarily, repeating type information is discouraged but weak type parameters such as Int do require clarification.
However, the usage at: is preferred over atIndex: even when the type is Int, with Index regarded as "needless" type information instead of clarification. This is illustrated by explicit examples in SE-0005/6, which interpret the guidelines. Such usage was confirmed by you, a principal guideline author, during review of SE-0023 as the intended interpretation of the guidelines, which was merely not made explicit in the guideline text.