[swift-users] If and Only If

[Lukas Stabe]

Imho, having iff is valuable since it makes it very clear that there are no corner-cases where something unexpected may happen. I can see from that one sentence that `hasSuffix` does exactly what I may want it to do, without needing to check if there is more documentation that might mention corner-cases.

I also don’t think it’s necessary to have iff explained in the Swift documentation, since learners can easily search the web or use something like “Look Up” from the context menu on OS X.

And even if they are sitting in a cave somewhere with no connection to the outside world and are learning Swift using just the provided documentation, they still have the fallback of assuming a typo and reading it as “if”, which is a reasonable approximation.

— Lukas

> On 08 Feb 2016, at 05:16, Brian Bauer via swift-users <swift-users at swift.org> wrote:
> 
> I apologize in advance if this subject has already been discussed and decided (as far as I can tell, the mailing list archives go back only about 60 days)…
> 
> When running through the Swift Tour portion of the Swift eBook, on page 10 there is a code snippet showing an example of the switch statement.  While typing that into an Xcode playground, I get a code completion popup on the “hasSuffix” method and the documentation says “Returns true iff self ends with suffix.”  This looks like a typo.  I know that it means “If and Only If” but to a less experienced developer this is likely to be misunderstood, especially as I can find no explanation for “iff” anywhere in the documentation.
> 
> The source of this documentation nugget is a comment in /stdlib/public/core/StringLegacy.swift, so I think discussion of the topic is relevant here.
> 
> Swift is touted as being friendly to new programmers and I don’t think it is reasonable to expect new programmers to understand “iff” and I also don’t think it is reasonable to spend a paragraph explaining “iff” at the beginning of an introduction to Swift, thus I suggest removing “iff” from all code comments that are likely to become user-facing documentation (the triple slash).  Or at the very least, user-facing documentation that is likely to be read by beginners.
> 
> A quick grep of the source gives me somewhere in the neighborhood of 130 instances of “iff” in a triple-slash comment, and I am more than happy to make all of the changes and submit pull requests.  Before taking on that work, however, I would like to know if such a change would be welcome or if anyone has a better idea, etc.
> 
> Thanks,
> Brian
> 
> _______________________________________________
> swift-users mailing list
> swift-users at swift.org
> https://lists.swift.org/mailman/listinfo/swift-users