4

My question is more oriented toward Python, but it may also be about JavaScript or other scripting languages.

I usually develop with statically typed languages (Java, C++, ActionScript, ...).

I like to use from time to time Python, and I also need to sometimes use JavaScript. These are dynamic typed languages. Nothing wrong with that, but I usually have lots of headaches to understand which parameters are needed in a function or in a method. It happens even if it is my own code with some docstrings! Maybe because the eye has to look somewhere else than in the definition of the function.

Of course, the answer should be in the documentation. But sometimes it is not clear at all, or because of the use of duck typing the documentation may be itself hard to write ("the first parameter is a function which must have a quack() method and a feathers(arg) method where arg is a string"). What I would very like is a kind of argument description inside the language itself (even if it would be optionnal, like in ActionScript).

What are your best practices to unambiguously describe the arguments of a function/method?

What about creating a special decorator (if using Python) which purpose would be to check the type of data when we use it (but as it will be used at runtime and not at writing time, what would be the point anyway)?

Do you think it should not be an issue? That doing more than current docstring would confuse a developer, or that my mind is too static-typing oriented?

Vincent Hiribarren
  • 5,254
  • 2
  • 41
  • 65
  • Forget about such a decorator. It's useless for documentation, highly complex (if done properly), introduces large overhead, even then endangers duck typing, and does not buy you any of the usual benefits of type checking (checking without running the program, the aforementioned documentation, optimization, etc.). You mind *is* "too static-typing oriented". –  Apr 29 '12 at 13:21
  • Maybe it is indeed :) But I have sometimes the impression to spend my time understanding the documentation of some Python libraries just to know what argument I must give; whereas I just have to look at the function/method signature with static typing. I know dynamic typing allows breaking some limitations of static typed languages, but still, if it implies unclear understanding of the use of a library, I feel I lose some time. – Vincent Hiribarren Apr 29 '12 at 18:01

2 Answers2

2

I don't know about Javascript, but Python has optional function annotations since version 3, which look like:

def haul(item: Haulable, *vargs: PackAnimal) -> Distance:

or:

def compile(source: "something compilable",
            filename: "where the compilable thing comes from",
            mode: "is this a single statement or a suite?"):

see the PEP for more information.

They are accessible at runtime and may even be used for type checking.

ch3ka
  • 11,792
  • 4
  • 31
  • 28
  • I believe that the OP is asking about the style of writing he should use, while you are suggesting a place he can put his writing… So I'm not sure this really answers the question. – David Wolever Apr 29 '12 at 13:08
  • He asked "What about creating a special decorator (if using Python) which purpose would be to check the type of data when we use it (but as it will be used at runtime and not at writing time, what would be the point anyway)?" - function annotations solve that question, as it serves both use cases. – ch3ka Apr 29 '12 at 13:12
  • Aaaah yes, totally forgot about this feature of Python 3. You are completely right. Still, I have to use the 2.x branch for now (due to some libraries) and the answer can be interesting for it. I will keep watching and upvoting other answers :) – Vincent Hiribarren Apr 29 '12 at 17:50
1

Why does duck typing make the documentation hard to write?

When ever you write a function, you write it assuming the arguments are of a particular type or confirm to a particular interface… So just document that.

For example, if you have a swim_in_pond(duck) method, there's no need to document "duck is expected to have quack(), swim(), and dive() methods" — in most cases, it's entirely sufficient to say "duck is an instance of Duck". Or, if it's important for you to document the "Duck-like" interface, I've found it helpful to declare a base class which serves as the documentation:

class DuckBase(object):
    def quack(self):
        """ Makes the duck quack. """

    def swim(self):
        """ Swims around.
            Assumes the duck is already in water.
            Updates the duck's position. """

    def dive(self):
        """ Dives either as deep as possible (either until the duck runs out of
            air, or it hits the bottom of the pond). """
David Wolever
  • 148,955
  • 89
  • 346
  • 502