Чтение кода на Python

Question

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

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 вы пишете docstring.И пока вы пишете это, вы понимаете, что вам нужно больше сказать об этом, чем «это строка». Вы должны сказать, какие данные находятся в строке, и какой формат она должна иметь, и что такое по умолчанию, и что-то об условиях ошибки.

И тогда вы понимаете, что должны были написать все это для своего статического языка. Несомненно, 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, чтобы убедиться, что ваши примеры Doc продолжать работать в будущем.

Answer 4

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

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

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

Answer 5

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

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

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

Answer 6

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

Например:

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

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

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

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

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