Using "iff" in documentation [closed]

Question

Is the term "iff" (as an abbreviation in "If and only if") commonly understood, when used in software documentation? I thought so, but recently a colleague had not heard about it so I am wondering if I should avoid this term or if I could assume that the general programmer knows it.

Example:

This function returns True iff the value of foo is larger than bar.

I decided to ask here instead of at english.stackexchange.com, because the target audience are programmers.

Answer 1

As you noticed, your colleague wasn't familiar with the term, so you can't assume that everybody (or even every software developer) knows it.

I would probably avoid using the term, mostly for two reasons:

1. this one (not everyone may be familiar, and documentation language should be quickly understandable)
2. it has a slightly elitist smell to it (this is probably just my personal perception, as I only encountered it in academic contexts)

Using precise language is a good thing, but some verbosity doesn't hurt :-)

Answer 2

If your colleague doesn't understand it, take it as a learning opportunity. The idea is not to dumb down things to the lowest common denominator, but to lift everyone up.

Please note that there is a middle ground between "dumbing down" and "being a smartass", So if you are asked about it you just say "that's the abbreviation for if and only if". No word about how everyone should know this.

Answer 3

Use iff iff the domain is appropriate.

From a dictionary:

iff

(mathematics, logic) Short for if and only if.

A rectangle is a square iff all four of its sides have the same length.

Assuming English text, iff you are writing a text in the domain of mathematics and logic, you may use iff.

That means you should not use the word if you are not writing a text in the domain of mathematics and logic.

This does not cover unrelated meanings in other languages.

Answer 4

The term iff for if-and-only-if may be understood in computer science and logic, and also bears an implied symmetry ("and not when not").

It is a useful operational term, with quite expressive power. But it needs always explanation, and the more or less implied exclusion of the negative case (when that is the case) needs also to be explained.

For example, using a foot note with a clear wording could be a solution.

This function returns True iff¹ the value of foo is larger than bar.

_{1 ) if-and-only-iff = necessary and sufficient condition. And not so when bar less or equal to foo.}

Answer 5

I would avoid using "iff" in documentation for a pragmatic reason: it's entirely too easy to double-tap the 'f' key, turning "if" into "iff", completely changing the meaning of what you wrote. It's a lot harder to accidentally type "if and only if" when you meant to type "if".

(I would consider using it iff the programming language in question has it as a keyword.)

Answer 6

Documentation should be unambiguous, obvious, and appropriately convey importance to the reader. It's important to know your audience; perhaps your readers are thoroughly digesting the documentation, but in most cases the majority of documentation is skimmed rather than read, and it's easy to misread "iff" as just "if". "if and only if" is a significant statement and "iff" does not do well to convey the weight of the statement to the reader. Also, "iff" strikes me as a notational symbol rather than something you would expect in plain language documentation.

Answer 7

I have two points.

1. The double 'f' syntax is not common in all programming languages. C# and Java are widely used examples of languages that do not use 'iff'. While 'iff' was taught in several mathematics courses required for my CS degree, those courses may not be required for programming degrees or certificates, and your fellow programmers may not have been exposed to the syntax.

2. Fully understand what your documentation is doing here:

This function returns True iff the value of foo is larger than bar.

This implies the value of false being the default state prior to the evaluation, and/or the return of false when foo is not larger than bar. Your documentation on this matter should be EXPLICIT. You should both avoid the shorthand, and explicitly include your Else condition.

Here is why I say point 2:

If the documentation is for an end user, e.g. API documentation, they should not have to guess if the returned state is True or False or NULL or guess if the Default state prior to evaluation is NULL or False.

Many readers will have read this and assumed "It's common sense that if something is not true, then it is false." And if you pause a moment longer, you will think of instances where you worked with application code where this is not the case."

If the documentation is for a developer to use in writing the code itself, you need to properly set the expectation of what you want to receive. Implied execution does not convey the entirety of your expectation, and is a great way to get back something that does not meet it.

Answer 8

Mathematical formalism is for the code; documentation should communicate clearly and precisely. In the given example, think about what you intend with the extra 'f'. The implication is: when foo isn't larger than bar, the function won't return True. Okay, but documentation is primarily about what the code will do, not about what it won't do.

Generally, if a function is returning a boolean, the natural assumption is that both True and False return values are possible, and that False is returned whenever True isn't. One doesn't expect, for example, the function to raise exceptions unless those cases are explicitly called out. So if that's what you mean, then say it. Common styles may range from:

Returns: foo > bar

This function returns a boolean indicating whether foo is greater than bar.

Any of these will be more concise than explaining what "iff" means.

On the other hand, if the function does something else in the other cases, you should say that, instead. Simply leaving it at "it doesn't return True in those cases" will lead the reader to guess, probably wrongly.

Answer 9

This function returns True iff the value of foo is larger than bar.

Do you actually mean this function returns (the result of the expression) foo > bar? it's not immediately clear: perhaps the function sometime does not return, or sometimes returns a value that is neither true nor false.

My take is leave the language of mathematical logic on the shelf, and use the langauge your audience, the programmer, will be most familiar with. Mixing languages leads to confusion. For exampls do "functions" in the programming language satisfy the mathematical definition of a function?

Answer 10

Many others here have stated that "iff" looks like a typo, yet none of them has suggested this approach: Make it so that it does not look like a typo.

This function returns True iff the value of foo is larger than bar.

This function returns `True` <i>iff</i> the value of `foo` is larger than `bar`.

(Note that *this syntax* renders as <em> (emphasis) rather than <i> (idiomatic text). Use that iff <i> is not a choice.)

Italicizing a word does not magically make the reader understand it, however, so an explanation of some kind is still necessary.

Answer 11

I think any good documentation should explain the concepts it uses:

• Explain (or provide a reference for) formal syntax notation being used
• Explain the meaning of symbols being used
• Explain abbreviations and acronyms being used
• Explain any keywords that may not be universally understood (like "iff", but you could also think of "implies")

Also I think the use of "iff" is justified to use (but see above) if the documentation is very formal (rather rare these days); still it could be spelled out ("if, and only if").

Answer 12

SURPRISE! Most readers aren't as educated as you are. It's the smart man's burden. And it can be shocking.

Think about it. The ONLY place anyone could ever encounter the term IFF is in a class on formal logic. It's just not part of the general vocabulary. Your fellow programmer didn't even understand it.

Smart people make the same mistake that stupid people do, which is why I call it The Universal Human Mistake: assuming that everyone else has the same knowledge and intent and motivation as you do.

I make the same mistake myself. It's universal. I assume everybody tells the truth when they say something, and that they want to know the truth when they ask me a question. But I once had a boss who was a compulsive liar. He explained that some people in the organization were "our enemies" and he always assumed everyone else was scheming and lying.

In fact, that's when I came up With the idea Of The Universal Human Mistake.

Answer 13

There are already several good answers (thank you all for contributing), but there is some detail I did not yet see anywhere.

Any documentation is not written for the experts (except for occasional reference), but for the people which have (and ideally they want too) to learn. So using "iff" should be more than appropriate.

However, there is a small catch - no one can learn anything if that anything is cryptic and not explained.

So what I would do is something like this:

1. Explain "iff" at the beginning of the document in the "Definitions and abbreviations" section, specifying at least one reliable source (e.g., a dictionary).
2. Spell "iff" with capital letters as IFF for a triple purpose: a) to make it obvious that the spelling is not a mistake, b) to draw the attention that there are 2 F's there actually - which carries a lot of important information and c) to make it obvious that, etymologically, the word is actually an abbreviation.

Without the clarifications above, anyone can infer or assume anything, which beats the purpose of writing the said documentation.

You are of course welcome to find other ways to transfer knowledge to the readers of your document, if you do not fully agree with my way.

Answer 14

The very rare times I want to use if-and-only-if in a computer program comment, I use the 3-character sequence <=> (or if that jumps out as an operator, <==>). It's a real logic symbol, which officially means the same thing as IFF (Wikipedia logical equivalence), but it more obviously indicates "I'm using a logic symbol". Briefly, if-and-only-if means a=>b and b=>a which is shortened to a<=>b and they both mean "both true or both false".

But I mean "very rare". Possibly very, very rare. For one thing, consider OP's "returns true if foo greater than bar". We wouldn't want to use iff or <=>, even if everyone knew it, since it's implied. If there were other ways to return true, we would have listed them. Saying things that are implied is confusing. Put another way, this is like adding "otherwise returns false".

For another, we rarely want to know IF vs. IFF. Say we're about to write a comment "restarts if idle for more than 20 seconds", but realize if-and-only-if is more accurate and write that. We've now told readers that there's currently no other way of restarting. We've let someone working on restart() know they can safely assume 20 seconds of inactivity. I don't think that's useful.

The few times I actually use <=> is explaining my logic. As a fake example "NOTE: amazingly, edges*2>=vertexes <=> maze can be solved!". I'm telling myself two things: checking for enough edges is a quick way to know the maze is usable; and checking for not enough edges is a quick way to know the maze isn't.

Answer 15

If and only if means something. Use it when that’s what you mean.

This is the age of google. It’s not that hard to look something up. So don't feel like you have to explain what it is. Explain why you need it.

However, don’t use this because you want to show off. Use it when it’s important.

I’d rather you made me think than made me guess.

As for the abbreviation, "iff", like all abbreviations it's considered wise to spell it out on first use. Like you did when you asked this question.