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.
That's why I said I think all of these changes are fine, and I still
think they are.
Stefan
Received on 2009-04-22 13:23:05 CEST