Стиль кодирования: как сделать очевидное определение типа параметра, который мы должны передать функции?

Question

Как лучше всего документировать тип параметров, которые функция ожидает получить?

Иногда функция использует только одно или два поля объекта.Иногда эти поля имеют общие имена (get (), set (), reset () и т. Д.).В этой ситуации мы должны оставить комментарий:

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

Есть ли более явный способ сделать это очевидным?Может быть, имя объекта должно содержать ожидаемое имя типа?

Answer 1

Принимая во внимание поведение Python 'duck-typing' (с поздним ограничением), было бы ошибкой требовать определенного типа.

Если вы знаете, какие типы ваша функция не должна принимать, вы можете вызвать исключение после их обнаружения; в противном случае просто вызовите исключение, если переданный объект не поддерживает соответствующий протокол.

Что касается документации, просто поместите требуемый протокол в строку документации.

Answer 2

Одной из сильных сторон Python является «типизация утки», которая заключается не в том, чтобы полагаться на реальный тип переменной, а на ее поведение.Поэтому я предлагаю вам задокументировать поле, которое должен содержать объект.

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

Answer 3

Прежде всего, назовите ваши методы правильно и используйте свойства, если они имеют смысл.

Вы должны попытаться научиться набирать утку. Это довольно полезно. А если нет, попробуйте и посмотрите, поможет ли абстрактные базовые классы делать то, что вы хотите.