CODEWITHSUNDEEP
coding-stylepython
sergzach
sergzach

Reputation: 6754

Coding Style: How to Make Obvious Determination of Parameter's Type We Have To Pass To a Function?

What is the best way to document the type of parameters that a function expects to receive?

Sometimes a function uses only one or two fields of an object. Sometimes this fields have common names (get(), set(), reset(), etc.). In this situation we must leave a comments:

    ... 
    @staticmethod
    def get( postId, obj ):
        """obj is instance of class Type1, not Type2"""
        inner = obj.get()

Is there a more explicit way to make it obvious? Maybe an object name should contain expecting typename?

Upvotes: 2

Views: 137

Answers (3)

cha0site
cha0site

Reputation: 10717

First of all, name your methods properly, and use properties if they make sense.

You should try to get the hang of duck-typing. It's pretty useful. And if not, try and see if abstract base classes helps you do what you want.

Upvotes: 1

jammon
jammon

Reputation: 3464

One strength of python is "duck typing", that is not to rely on the actual type of a variable, but on its behaviour. So I'd suggest, that you document the field, that the object should contain.

"""obj should have a field 'foo' like in class 'bar' or 'baz' """

Upvotes: 3

Marcin
Marcin

Reputation: 49816

Given python's 'duck-typing' (late bound) behaviour, it would be a mistake to require a particular type.

If you know which types your function must not take, you can raise an exception after detecting those; otherwise, simply raise an exception if the object passed does not support the appropriate protocol.

As to documentation, just put the required protocol in the docstring.

Upvotes: 7

Related Questions