While approving and publishing content for a public web site today, I came across a series of links that ultimately led me to Interchange, and specifically to a documentation page about applying discounts to e-commerce items in the Interchange system. While I applaud them for having this much documentation, the code examples on the page leave me scratching my head. For example, to apply a 25% discount to item 00-342, one writes [discount 00-342] $s * .75 [/discount]. See the problem? What does $s mean?!. Fortunately, it is documented on that page that the [discount] tag creates two variables - $s and $q, which mean respectively mean subtotal and quantity. So - why not have $subtotal and $quantity? [discount 00-342] $subtotal * 0.75 [/discount] communicates intent with greater clarity than just $s.
The documentation gets even more fun when a complex discount computation example is shown, using Perl:
[discount 00-343] return $s if $q == 1; my $p = $s/$q; my $t = ($q - 1) * $p; $t .= 0.01; return $t; [/discount]This is documented as "Here is an example of a discount for item code 00-343 which prices the second one ordered at 1 cent:". It took me a while to grasp the meaning of $p and $t here. First I was thinking "is $t tax?" before remembering this is discounts we're talking about here. Perlisms aside, this code would be vastly improved by expanded variable names.
The worst part about this is - these are examples in the documentation. Is readability and maintainability just not a factor in the Perl world? I mean - the Python community jokes about it all the time, but I didn't think it was this real. It may be fine to write code like this for yourself, but as an example to show others - it sets and spreads a bad example, in my opinion.
For fun, in bad Python, the above would probably look like this:
[discount 00-343] if q == 1: return s p = s/q t = (q-1) * p t += 0.01 return t [/discount]See? Just as bad - just with a bit less line noise. It shows that you can write bad code in any language. For more fun, let's try this in 'good' Python:
[discount 00-343]
if quantity == 1:
return subtotal
price = subtotal / quantity
total = (quantity - 1) * price
total += 0.01
return total
[/discount]
Even without comments (which would help this code - ie, just a docstring or comment at the top that says "if more than one item, charge one cent for the second one" would be helpful), the intent is clearer. So, when you revisit the code in four months or even a year, you at least know what you were trying to do. Trust me - it makes life so much nicer when you take the extra few seconds to give variables, methods, classes, etc, meaningful names.
Note: on the About Interchange page, they supply this caveat: "Interchange is not presented as being easy to use, easy to install, or bug-free." At least they're honest. Zope could probably benefit from this honesty up front. But still - $s?!