[Tutor] please return flys in ointment

[Steven D'Aprano]

On 07/07/13 07:38, Jim Mooney wrote:
> I reworked my numbers_to_name program so I can actually follow the logic.
> Since I think the best way to learn is to follow something through to
> completion, I'll put it online so I learn how to do that. But naturally,
> lest I look dumb, I'd appreciate criticism, improvements of bad form, or if
> anyone can break it, let me know ;') .


Let's look at your overall program design:

You should always separate *interface* from *functionality*. As it stands now, your make_triplets_from_input() function does both: it interacts with the user, and performs critical functionality. That means you cannot [easily] either test, or use, that critical functionality *except* interactively.


And that brings us to the second issue: with respect, your API (Application Programming Interface) sucks. You have two functions, one to get *a string* of digits directly from the user and convert them to triplets, and one to convert triplets into a string. Nowhere do you have a function to convert *numbers* to names, despite the alleged name of your program. (Programmers who write programs that lie about what they do occupy a special circle of Hell, along with those who talk during movies, people listening to music on their mp3-player so loudly that others can hear it through their headphones, and anyone who wears Lynx/Axe body spray.) So I suggest the following public function:

number_to_words: takes an integer and converts to words

     >>> number_to_words(156)
     'one hundred and fifty six'


plus some sort of function to handle repeatedly asking the user for a number and converting it. Anything else is just support for the number_to_words function.


Thirdly, except for the most throw-away "who cares" scripts, you should try to design your programs so that they have a separate main() function which only runs when you explicitly run the program, not when you import it. That way this number_to_words function can be reused in other programs, just by importing it.


Lastly, you're annoyingly cautious about version numbers. I haven't studied your code in sufficient detail to be sure, but nothing stands out that would prevent your code from working in at least Python 2.5-3.3 inclusive. And when 3.4-3.9 come out over the next decade or so, I would expect your code to continue working. There's no need to *prohibit other versions* -- it's enough to say "tested in versions 2.7 and 3.3", and then wait for bug reports to come in:

  "doesn't work in Python 1.5"
  "doesn't work in Python 2.6, here's how to fix it"

sort of thing. You can then say you won't support anything as old as 1.5 (I don't even consider supporting anything below 2.4) and choose whether or not to accept patches.

More to follow...


-- 
Steven