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

[Dave Abrahams]

on Fri Jan 29 2016, Erica Sadun <swift-evolution at swift.org> wrote:

>> 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

This works great so far.  I think you can say

  - use nouns for methods with no side effects (or only incidental ones,
    like logging)
  - use verbs for methods with significant side-effects

and you can stop there.  Why does this have to be more complicated than
that?

>   - 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). 

No, it's creating the past participle.  We had this checked by a
linguist :-).

http://apple.github.io/swift-internals/api-design-guidelines/index.html
uses the correct terminology but apparently we haven't propagated the
changes up to Swift.org 

*goes to fix up Swift.org*

> 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.)

These are the present participles.  The linguist again :-)

-- 
-Dave