Discussion on some Code Issues

[Chris Angelico]

On Mon, Jul 9, 2012 at 10:57 AM, Steven D'Aprano
<steve+comp.lang.python at pearwood.info> wrote:
> On Mon, 09 Jul 2012 07:54:47 +1000, Chris Angelico wrote:
>
>> It's like
>> the difference between reminder text on a Magic: The Gathering card and
>> the actual entries in the Comprehensive Rules. Perfect example is the
>> "Madness" ability - the reminder text explains the ability, but uses
>> language that actually is quite incorrect. It's a better explanation,
>> though.
>
> Hang on, you say that an explanation which is "quite incorrect" is
> *better* than one which is correct?
>
> I can see why they call the card "Madness".
>
> :-P

Agreed about the ability name :) The fact is, though, that when you're
explaining something, it's often better to have a one-sentence
explanation that's not quite technically accurate than two paragraphs
explaining it in multiple steps and are opaque to anyone who doesn't
have the rules-lawyer mind. (I happen to have such a mind. It's not
always a good thing, but it makes me a better debugger.)

Does it really hurt to anthropomorphize and say that "Python looks for
modules in the directories in sys.path" instead of "Module lookup
consists of iterating over the elements in sys.path [and that's
leaving out the worst-case DFS where you explain THAT in detail],
calling combine_path [or whatever it is] with the element and the
module name, and attempting to stat/open the result"? While your
listener's getting bogged down in unnecessary detail, s/he isn't
grokking the overall purpose of what you're saying.

One option is more accurate. The other is far more helpful.

ChrisA