Re: some comments and complaints on the code (issue 5651069)

[Han-Wen Nienhuys]

On Sat, Feb 11, 2012 at 8:31 AM,  <address@hidden> wrote:

>> somebody proposed a change, it was resisted because the do{}
>
> flip(d)!=UP idiom
>>
>> seemed simple enough to be acceptable.
>
>
> It took us a while to figure out what's going on with the do{}
> flip(d)!=UP thing.
> If it was up to me, i'd just write everything twice, following the rule
> "1, 2, many" :)

it would double the size of already rather complicated code. My
experience has also been that its easy for a bug to sneak into the
more complicated expressions.  To make things worse, you typically
have to double the number of test cases to provide coverage for both
up and down versions of all logic.


> Well, the main point of the comment is not describing parameters, but
> the function itself.  Believe me or not, we spent 10 minutes figuring
> out _what the hell_ are apes doing here and whether there are any
> bananas involved.
> It's stupid, i know.  But there must exist a way of writing code that is
> understandable for the newcomers after second reading, not after 10
> minutes.

I disagree.  Reading code the first time is hard, that is true, but
unless anything surprising is happening, it does not deserve a
comment. The more you read code, the easier it becomes, and think of
this as you learning how to read.  In an analog: beginners books may
feature simpler words, hy-phe-na-te all words explicitly and use
pictures, but that doesn't mean literature for grownups should have
those.

There is also a practical reason to minimize: comments easily are
forgotten when changing code, so they tend go out of date faster.

-- 
Han-Wen Nienhuys - address@hidden - http://www.xs4all.nl/~hanwen