Читаемость кода Python

Question

У меня есть опыт программирования со статически типизированными языками. Сейчас при написании кода на Python я испытываю трудности с его читабельностью. Допустим, у меня есть класс Host :

class Host(object):
  def __init__(self, name, network_interface):
    self.name = name
    self.network_interface = network_interface

Я не понимаю из этого определения, каким должно быть " network_interface ". Это строка , например " eth0 ", или это экземпляр класса NetworkInterface ? Единственный способ решить эту проблему - документировать код с помощью " docstring ". Примерно так:

class Host(object):
  ''' Attributes:
      @name: a string
      @network_interface: an instance of class NetworkInterface'''

Или, может быть, существуют соглашения об именах для подобных вещей?

Answer 1

Использование динамических языков научит вас кое-чему о статических языках: вся помощь, которую вы получили от статического языка, который вы сейчас упускаете в динамическом языке, оказалась не такой уж полезной.

Чтобы использовать ваш пример на статическом языке, вы должны знать, что параметр является строкой, а в Python - нет. Итак, в Python вы пишете строку документации. И пока вы пишете это, вы понимаете, что можете сказать об этом больше, чем «это строка». Вы должны сказать, какие данные находятся в строке, и в каком формате они должны быть, каковы значения по умолчанию и что-то об условиях ошибки.

И тогда вы понимаете, что должны были записать все это и для своего статического языка. Конечно, Java заставит вас знать, что это строка, но есть все эти другие детали, которые необходимо указать, и вам придется выполнять эту работу вручную на любом языке.

Answer 2

Соглашения о документах: PEP 257 .

Пример, следующий за этим форматом для указания аргументов, вы можете добавить типы, если они имеют значение:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Был также отклоненный PEP для строк документации для атрибутов (а не аргументов конструктора).

Answer 3

Наиболее питонное решение - документировать с примерами. Если возможно, укажите, какие операции должен поддерживать объект, чтобы быть приемлемым, а не определенного типа.

class Host(object):
  def __init__(self, name, network_interface)
    """Initialise host with given name and network_interface.

    network_interface -- must support the same operations as NetworkInterface

    >>> network_interface = NetworkInterface()
    >>> host = Host("my_host", network_interface)

    """
    ...

На этом этапе подключите ваш источник к doctest , чтобы убедиться, что ваши примеры документов продолжают работать в будущем.

Answer 4

Лично я нашел очень полезным использовать pylint для проверки моего кода.

Если вы будете следовать предложению Pylint почти автоматически, ваш код станет более читабельным, Вы улучшите свои навыки написания на Python, соблюдаете правила именования. Вы также можете определить свои собственные соглашения об именах и так далее. Это очень полезно специально для начинающего питона.

Я предлагаю вам использовать.

Answer 5

Python, хотя и не такой явно типизированный, как C или Java, все же печатается и будет выдавать исключения, если вы делаете вещи с типами, которые просто не сочетаются друг с другом.

С этой целью, если вы беспокоитесь о том, что ваш код используется правильно, поддерживается правильно и т. Д., Просто используйте строки документации, комментарии или даже более явные имена переменных, чтобы указать, какой тип должен быть.

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

Answer 6

Одним из преимуществ статической типизации является то, что типы являются формой документации. При программировании на Python вы можете более гибко и свободно документировать. Конечно, в вашем примере вы хотите сказать, что network_interface должен реализовывать NetworkInterface, но во многих случаях тип очевиден из контекста, имени переменной или по соглашению, и в этих случаях, опуская очевидное, вы можете создать более читаемый код. Общим является описание значения параметра и неявное указание типа.

Например:

def Bar(foo, count):
    """Bar the foo the given number of times."""
    ...

Это описывает функцию кратко и точно. То, что означает foo и bar, будет очевидно из контекста, и это число (положительное) целое число неявно.

Для вашего примера я бы просто упомянул тип в строке документа:

"""Create a named host on the given NetworkInterface."""

Это короче, более читабельно и содержит больше информации, чем список типов.