(Aside: I really don’t know what to think of that code on the right hand side of the lambda. It’s more or less forced on me by the fact that that body of a lambda is an expression so I can’t use if. It’s also a compelling reason why Python will probably continue to use Iverson’s Convention for some while.)

I’m not saying that it’s necessarily good idea to define max like this, it’s a bit of a contrived example, but when you get used to higher order functions you end up defining a lot of really useful functions like this instead of using def statements. Sometimes such a function will be sufficiently useful that it will form part of a public interface, in which case it needs documenting.

5 Responses to “Python: Documenting Higher-Order Artefacts”

It’s bad to think of __doc__ and other __foo__ methods as secret or tricky. They are important parts of the language that any mid-level python programmer should know and use. This use of docstrings is perfect example.

Also, I’m fairly certain I read about way (or maybe a feature in 3000?) to change the argument list. But, I’ve never used it.

Adding the documentation as an optional paramter to curry is of course way simpler and equally flexible. Equally flexible since I can always overwrite my automatically generated documentation if I want to.

I was attracted by the prospect that at least some documentation could be produced automatically.

Thanks Paul. I had vaguely remembered a new “if expression” thing, but I couldn’t find it when I looked for it. It’s new in 2.5 (which is fine, it just means I won’t be using it in earnest for a while).

I like the fact that “if” is an expression, but the syntax somehow rather unpleasantly reminds me of perl.