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.
* It's a well known term of art among developers
* If you see "iff" more than once, you're going to be curious
* Hopefully you'll type "what does iff mean" into Google at that point and Google will respond like this: Imgur: The magic of the Internet
* see also: Dear Erica: What’s iff? — Erica Sadun
-- E
···
On Feb 7, 2016, at 9:16 PM, Brian Bauer via swift-users <swift-users@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.
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@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.
I, as a none-native-English-speaker, do think iff as a type error at first
for a long time. And I doubt it as I see it everywhere. But I have never
look it up.
I just use iff as if and do not think there is a much difference. I thank
to Brian for he finally letting me know the real meaning. I think if itself
means iff, but I am not computer major, so I can only represent as a layman.
zhaoxin
···
On Tue, Feb 9, 2016 at 2:18 AM, Erica Sadun via swift-users < swift-users@swift.org> wrote:
I personally wouldn't change it.
A few thoughts:
* It's a well known term of art among developers
* If you see "iff" more than once, you're going to be curious
* Hopefully you'll type "*what does iff mean*" into Google at that point
and Google will respond like this: Imgur: The magic of the Internet
* see also: Dear Erica: What’s iff? — Erica Sadun
-- E
On Feb 7, 2016, at 9:16 PM, Brian Bauer via swift-users < > swift-users@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.
IMO, clarity is more important than brevity, particularly when novices and non-English speakers might not "get it".
What's the harm in using "if and only if" instead of "iff"? IMO, none. I suggest using words, not a TLA.
Don Wills
···
On Feb 8, 2016, at 7:35 PM, zhaoxin肇鑫 via swift-users <swift-users@swift.org> wrote:
I, as a none-native-English-speaker, do think iff as a type error at first for a long time. And I doubt it as I see it everywhere. But I have never look it up.
I just use iff as if and do not think there is a much difference. I thank to Brian for he finally letting me know the real meaning. I think if itself means iff, but I am not computer major, so I can only represent as a layman.
zhaoxin
On Tue, Feb 9, 2016 at 2:18 AM, Erica Sadun via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
I personally wouldn't change it.
A few thoughts:
* It's a well known term of art among developers
* If you see "iff" more than once, you're going to be curious
* Hopefully you'll type "what does iff mean" into Google at that point and Google will respond like this: Imgur: The magic of the Internet
* see also: Dear Erica: What’s iff? — Erica Sadun
-- E
On Feb 7, 2016, at 9:16 PM, Brian Bauer via swift-users <swift-users@swift.org <mailto:swift-users@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.
I would argue that "iff" is actually clearer and less brief, even though
it's fewer letters, because it forces you to stop and think "oh, they mean
it in the rigorous, mathematical sense of the phrase." And if you haven't
encountered it in math, you're far more likely to Google it. They
technically mean the same thing, but "if and only if" is much easier to
gloss over!
Andrew
···
On Mon, Feb 8, 2016 at 8:45 PM Don Wills via swift-users < swift-users@swift.org> wrote:
IMO, clarity is more important than brevity, particularly when novices and
non-English speakers might not "get it".
What's the harm in using "if and only if" instead of "iff"? IMO, none. I
suggest using words, not a TLA.
Don Wills
On Feb 8, 2016, at 7:35 PM, zhaoxin肇鑫 via swift-users < > swift-users@swift.org> wrote:
I, as a none-native-English-speaker, do think iff as a type error at first
for a long time. And I doubt it as I see it everywhere. But I have never
look it up.
I just use iff as if and do not think there is a much difference. I thank
to Brian for he finally letting me know the real meaning. I think if itself
means iff, but I am not computer major, so I can only represent as a layman.
zhaoxin
On Tue, Feb 9, 2016 at 2:18 AM, Erica Sadun via swift-users < > swift-users@swift.org> wrote:
I personally wouldn't change it.
A few thoughts:
* It's a well known term of art among developers
* If you see "iff" more than once, you're going to be curious
* Hopefully you'll type "*what does iff mean*" into Google at that point
and Google will respond like this: Imgur: The magic of the Internet
* see also: Dear Erica: What’s iff? — Erica Sadun
-- E
On Feb 7, 2016, at 9:16 PM, Brian Bauer via swift-users < >> swift-users@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.
"Iff" may be clearer to you, but it is likely a complete unknown to many beginning programmers and to non-English speakers as the previous comment shows. Many would likely just think it's a typo. I really don't see the harm in spelling it out.
And to posit that the equivalent four words is somehow less obvious is ridiculous.
Don Wills
···
On Feb 9, 2016, at 9:04 AM, Andrew Clissold <andrewclissold@gmail.com> wrote:
I would argue that "iff" is actually clearer and less brief, even though it's fewer letters, because it forces you to stop and think "oh, they mean it in the rigorous, mathematical sense of the phrase." And if you haven't encountered it in math, you're far more likely to Google it. They technically mean the same thing, but "if and only if" is much easier to gloss over!
Andrew
On Mon, Feb 8, 2016 at 8:45 PM Don Wills via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
IMO, clarity is more important than brevity, particularly when novices and non-English speakers might not "get it".
What's the harm in using "if and only if" instead of "iff"? IMO, none. I suggest using words, not a TLA.
Don Wills
On Feb 8, 2016, at 7:35 PM, zhaoxin肇鑫 via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
I, as a none-native-English-speaker, do think iff as a type error at first for a long time. And I doubt it as I see it everywhere. But I have never look it up.
I just use iff as if and do not think there is a much difference. I thank to Brian for he finally letting me know the real meaning. I think if itself means iff, but I am not computer major, so I can only represent as a layman.
zhaoxin
On Tue, Feb 9, 2016 at 2:18 AM, Erica Sadun via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
I personally wouldn't change it.
A few thoughts:
* It's a well known term of art among developers
* If you see "iff" more than once, you're going to be curious
* Hopefully you'll type "what does iff mean" into Google at that point and Google will respond like this: Imgur: The magic of the Internet
* see also: Dear Erica: What’s iff? — Erica Sadun
-- E
On Feb 7, 2016, at 9:16 PM, Brian Bauer via swift-users <swift-users@swift.org <mailto:swift-users@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.
I don't think Andrew's point was ridiculous. If you feel strongly about changing this, consider filing an enhancement request at bugs.swift.org.
-- E
···
On Feb 9, 2016, at 9:15 AM, Don Wills via swift-users <swift-users@swift.org> wrote:
"Iff" may be clearer to you, but it is likely a complete unknown to many beginning programmers and to non-English speakers as the previous comment shows. Many would likely just think it's a typo. I really don't see the harm in spelling it out.
And to posit that the equivalent four words is somehow less obvious is ridiculous.
Don Wills
On Feb 9, 2016, at 9:04 AM, Andrew Clissold <andrewclissold@gmail.com <mailto:andrewclissold@gmail.com>> wrote:
I would argue that "iff" is actually clearer and less brief, even though it's fewer letters, because it forces you to stop and think "oh, they mean it in the rigorous, mathematical sense of the phrase." And if you haven't encountered it in math, you're far more likely to Google it. They technically mean the same thing, but "if and only if" is much easier to gloss over!
Andrew
On Mon, Feb 8, 2016 at 8:45 PM Don Wills via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
IMO, clarity is more important than brevity, particularly when novices and non-English speakers might not "get it".
What's the harm in using "if and only if" instead of "iff"? IMO, none. I suggest using words, not a TLA.
Don Wills
On Feb 8, 2016, at 7:35 PM, zhaoxin肇鑫 via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
I, as a none-native-English-speaker, do think iff as a type error at first for a long time. And I doubt it as I see it everywhere. But I have never look it up.
I just use iff as if and do not think there is a much difference. I thank to Brian for he finally letting me know the real meaning. I think if itself means iff, but I am not computer major, so I can only represent as a layman.
zhaoxin
On Tue, Feb 9, 2016 at 2:18 AM, Erica Sadun via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
I personally wouldn't change it.
A few thoughts:
* It's a well known term of art among developers
* If you see "iff" more than once, you're going to be curious
* Hopefully you'll type "what does iff mean" into Google at that point and Google will respond like this: Imgur: The magic of the Internet
* see also: Dear Erica: What’s iff? — Erica Sadun
-- E
On Feb 7, 2016, at 9:16 PM, Brian Bauer via swift-users <swift-users@swift.org <mailto:swift-users@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.