On Thu, 04 Dec 2008 10:44:33 -0600, Chris Mellon wrote: > On Thu, Dec 4, 2008 at 8:45 AM, Steven D'Aprano > <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list