"as" keyword woes

[Steven D'Aprano]

On Thu, 04 Dec 2008 10:44:33 -0600, Chris Mellon wrote:

> On Thu, Dec 4, 2008 at 8:45 AM, Steven D'Aprano
> <steve at remove-this-cybersource.com.au> wrote:
>> On Thu, 04 Dec 2008 20:53:38 +1000, James Mills wrote:
>>
>>> Readability of your code becomes very important especially if you're
>>> working with many developers over time.
>>>
>>> 1. Use sensible meaningful names.
>>> 2. Don't use abbreviations.
>>
>> This is excellent advice, but remember, what is a sensible meaningful
>> name is domain-specific. In a maths library, this would be sensible:
>>
>> def poly(x):
>>    return 4*x**3 -2*x**2 +3*x -7
>>
>> and this ridiculous:
>>
>> def poly(real_number):
>>    return 4*real_number**3 -2*real_number**2 +3*real_number -7
>>
>>
>>
> I actually wonder. The former is "sensible" in a math context because
> there's a very long tradition in mathematics of using terse, inscrutable
> placeholders for terms. 

It's only inscrutable to those who don't speak the language, in the same 
way that those who don't read English would find "The cat sat on the mat" 
to be inscrutable, or those with no programming experience at all would 
find:

if myList is not None: return [item.method() for item in myList.process()]

fairly mystifying. It almost looks like English, but what's with the 
weird punctuation and non-standard use of capitals? 



> I'm not a mathematician and I don't know
> anything about the history of mathematical notation, but I'd guess this
> has something to do with the fact that maths has historically been done
> with a pencil and paper, and that terseness is an important quality when
> you have a limited canvas and lots of stuff to write.

I don't believe "limited canvas" is a major factor, because the 
availability of paper is only rarely a limiting factor. (However, there 
have been periods where paper or its equivalent was a rare and precious 
commodity.) Having lots of stuff to write by hand is a real factor 
though, especially since in a typical proof each line is very similar to 
the previous line.


> Aside from the cultural indoctrination, though (and that may be a real
> and strong force when dealing with math software, and I don't want to
> discount it in general, just for purposes of this discussion) why is it
> more sensible to use "x" here instead of "number" or "real" or
> "real_number" or something else?

Because the long names actually distract from the essential semantics of 
the problem being worked on. Consider my example:

return 4*x**3 -2*x**2 +3*x -7

Translated into English, this would mean:

Think of a number and call it x, and by convention it is a real number; 
cube it and multiply by four;
subtract two times the square of it;
add three times it;
subtract 7


Compare this:

return 4*real_number**3 -2*real_number**2 +3*real_number -7

As a mathematician, I would read that as:

Think of a number and call it real_number; 
cube it and multiply by four, and don't forget the number needs to be a 
real number;
subtract two times the square of it, and remember the number is a real 
number;
add three times it, and did I mention that it has to be a real number?;
subtract 7

Explicit is not *always* better than implicit, and terseness *is* a 
virtue (up to a point!) which is why we don't do this:

Define a function called myFunc which takes one argument called foo. The 
instructions to be executed when calling myFunc start here:
    if the value of the argument foo is identical to the value of the 
keyword None then:
        change the value of the argument foo to the result returned by 
the function calc_foo, passing no arguments to it
    otherwise do nothing
    ...

but prefer the (slightly) terse and (moderately) implicit:

def myFunc(foo, bar):
    if foo is None:
         foo = calc_foo()
    ...

Thank goodness we don't have to program in verbose, explicit English!

In general, most mathematical expressions will involve a small number of 
variables, and what they represent are obvious from context, at least for 
those familiar with the problem domain. Those who aren't familiar with 
the problem domain aren't expected to work on either developing the 
expression in the first place, or maintaining it, in whatever sense 
mathematics is expected to be maintained. Although the problem domain 
naively seems narrow ("huh, who needs to understand complex numbers?") it 
is actually very abstract and hence can in principle be applied to many 
different problems.

Contrast this with some arbitrary non-mathematical program. It might 
involve many variables rather than a few, and those variables might be 
rich objects with many attributes instead of simple numbers. The problem 
domain is often very concrete: *this* one specific business process, 
meaningful to only this department of that organisation, or at least to 
those just like them. Because concrete is more narrow than abstract, and 
because people who don't understand the problem domain are expected to 
maintain the software, you can't rely on implicit knowledge: you have to 
be explicit, and hence verbose, self-explanatory names are a virtue.


-- 
Steven