[swift-evolution] [Review] SE-0006 Apply API Guidelines to the Standard Library

[Erica Sadun]

> On Jan 29, 2016, at 2:14 PM, Dave Abrahams <dabrahams at apple.com> wrote:
> 
> 
> on Fri Jan 29 2016, Erica Sadun <erica-AT-ericasadun.com <http://erica-at-ericasadun.com/>> wrote:
> 
>> The "too specific" I'm railing against is that naming guidance should not depend on implementation details to
>> the point it creates Hungarian Swiftisms.
> 
> I understand the overall concern, but I don't think these guidelines do
> that.  Whether something has side effects is hardly an implementation
> detail.  


I've been spending a ridiculous amount of time trying to hash out exactly what I'd prefer because this overlaps with another project I'm currently working on:

  - use nouns for unambiguously functional items without side effects (distanceTo(), successor)
  - use verbs for unambiguously procedural items
  - prefer verbs for items with side effects, whether there's mutation or other real-world effects
  - Otherwise decide what the most relevant description of the member's purpose is: to return a value or to perform an action. In such cases, name nouny-things with nouns and verby-things with verbs.

Under the current system, you could have:

// This is a mutating version
mutating func login(credential: SomeCredentialType) 
-> LoginTokenType? {
    ...
    // store login time, etc in self
    ...
    return successToken
}
// This is a non-mutating version with side effects
func login(credential: SomeCredentialType) 
-> LoginTokenType? {
    ...
    // store login time, etc in a file on disk
    ...
    return successToken
}

// This is a non-mutating version
func login(credential: SomeCredentialType) 
-> LoginTokenType? {
    ...
    return successToken
}

All three versions are verb named as their primary purpose is to log in. But what if they're recast as tokenForCredential, with their primary purpose
being to fetch a token?

For the first example, you could refactor with a purely functional tokenForCredential and a mutating login function that updates self.

But what about the second example, that does not mutate, whose primary purpose is to return a token, but that introduces side effects by writing to disk? Should this be verb named and re-factored? (probably) If so, using "mutating"/"non-mutating" is not sufficient to offer guidance and overly specific as to implementation details. In other words, "hungarian".

One final point: I think the -ed/-ing advice is wrong. Adding "ed" isn't really creating a past tense verb (reversed). It's creating an adjective with an implied noun. Same rule for -ing. Like "ed", applying "ing" can create an adjective form with an implied subject. (Words ending with "ing" are not always gerunds. It might sound daring and frightning but it's true.)

-- E

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