On Wed, Apr 22, 2009 at 1:22 PM, Stefan Sperling <stsp_at_elego.de> wrote:
> On Wed, Apr 22, 2009 at 09:50:29AM +1000, Gavin Baumanis wrote:
>> My view is to go for the simplest explanation possible - to leave out
>> colloquialisms / local language constructs and to be as non-technical
>> as possible for the purposes of documenting code.
>> Well written code - should be sufficient for those with the technical
>> understanding of the project and the plain-english description should
>> allow the not-so technically apt to fully understand (at least) the
>> intent of the code.
>
> I was confused by iff, too, at first sight. Luckily I had Stephen
> Butler next to me, who is a native speaker and could explain.
>
> I don't mind learning new things about the English language at all,
> though. So I welcome use of constructs that might even only be used
> locally where the person writing the comment is coming from, as long
> as they appear in some dictionary or can otherwise be deciphered.
>
> But I understand that iff may seem like a typo to many non-native speakers,
> until they discover that it is being used in a *lot* of comments. Then,
> if they don't look up the term (e.g. at http://en.wikipedia.org/wiki/Iff),
> being uncertain about its intended meaning causes uncertainty about
> their understanding of the comment, rather than the certainty which
> "if and only if" is supposed to imply.
>
> I wouldn't go as far as removing all iffs from the tree in a massive
> series of patches. Please don't. But if the occasional iff gets
> transformed into "if and only if", or even just "if" as a drive-by
> side effect of a change, that's fine by me.
Hmmm. You obviously don't have a math background :-) It's a very
common thing in math texts to have "if and only if" shortened to iff.
I guess it all depends where you're coming from.
A must say that "if and only if" has a very different meaning that
"if" by itself, so please don't change it to "if" alone: it's a
different contract: the "and only if" part is an additional guarantee
the interface is making.
Bye,
Erik.
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1859848
Received on 2009-04-22 14:34:33 CEST