Question

I have some functions in my code that accept either an object or an iterable of objects as input. I was taught to use meaningful names for everything, but I am not sure how to comply here. What should I call a parameter that can a sinlge object or an iterable of objects? I have come up with two ideas, but I don’t like either of them:

1. FooOrManyFoos – This expresses what goes on, but I could imagine that someone not used to it could have trouble understanding what it means right away
2. param – Some generic name. This makes clear that it can be several things, but does explain nothing about what the parameter is used for.

Normally I call iterables of objects just the plural of what I would call a single object. I know this might seem a little bit compulsive, but Python is supposed to be (among others) about readability.

Answer 1

I have some functions in my code that accept either an object or an iterable of objects as input.

This is a very exceptional and often very bad thing to do. It’s trivially avoidable.

i.e., pass [foo] instead of foo when calling this function.

The only time you can justify doing this is when (1) you have an installed base of software that expects one form (iterable or singleton) and (2) you have to expand it to support the other use case. So. You only do this when expanding an existing function that has an existing code base.

If this is new development, Do Not Do This.

I have come up with two ideas, but I don’t like either of them:

[Only two?]

FooOrManyFoos – This expresses what goes on, but I could imagine that someone not used to it could have trouble understanding what it means right away

What? Are you saying you provide NO other documentation, and no other training? No support? No advice? Who is the “someone not used to it”? Talk to them. Don’t assume or imagine things about them.

Also, don’t use Leading Upper Case Names.

param – Some generic name. This makes clear that it can be several things, but does explain nothing about what the parameter is used for.

Terrible. Never. Do. This.

I looked in the Python library for examples. Most of the functions that do this have simple descriptions.

http://docs.python.org/library/functions.html#isinstance

isinstance(object, classinfo)

They call it “classinfo” and it can be a class or a tuple of classes.

You could do that, too.

You must consider the common use case and the exceptions. Follow the 80/20 rule.

1. 80% of the time, you can replace this with an iterable and not have this problem.

2. In the remaining 20% of the cases, you have an installed base of software built around an assumption (either iterable or single item) and you need to add the other case. Don’t change the name, just change the documentation. If it used to say “foo” it still says “foo” but you make it accept an iterable of “foo’s” without making any change to the parameters. If it used to say “foo_list” or “foo_iter”, then it still says “foo_list” or “foo_iter” but it will quietly tolerate a singleton without breaking.

   • 80% of the code is the legacy (“foo” or “foo_list”)

   • 20% of the code is the new feature (“foo” can be an iterable or “foo_list” can be a single object.)