Блог

Главная - Вопросы по программированию - Ввод аннотаций с помощью строк документации в стиле Google

Ввод аннотаций с помощью строк документации в стиле Google

#python

#python

Вопрос:

При использовании строк документов в стиле Google и аннотаций типов подсказки типа удваиваются.

Есть ли консенсус сообщества о том, как этого избежать?

Раздражающее удвоение типов:

 def sum(a: int, b: int) -> int:
    """ blah blah
    
    Args: 
        a (int): value 1
        b (int): value 2
    Returns:
        int: summed values
    """
    return a   b

Должны ли типы быть исключены из строки документации таким образом?

 def sum(a: int, b: int) -> int:
    """ blah blah
    
    Args: 
        a: value 1
        b: value 2
    Returns:
       summed values
    """
    return a   b

Я не видел, чтобы кто-нибудь еще упоминал об этом, но я не могу быть единственным, кто не уверен в наилучшем подходе здесь.

Ответ №1:

Да, вам нужны только подсказки типа ИЛИ аннотации в аргументах и возвратах, а не оба.

Ссылки

Согласно руководству по стилю Google Python: «Описание должно включать требуемые типы, если код не содержит аннотаций соответствующего типа».

Документы Sphinx также поощряют это в своем примере кода:

 
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

Комментарии:

1. Не работает с какими-либо дополнительными подсказками, например. param1 (:obj:`int`, optional): Optional param — невозможно написать его без дублирования типа…

Ответ №2:

Это очень ИМХО, но я не думаю, что перечисление всех параметров в строке документа имеет большое значение, если у вас есть приличные имена и аннотации типов.

 def sum(a: int, b: int) -> int:
    """Returns the result of adding the inputs together."""
    return a   b

более чем достаточно понятен IMO. В реальной жизни с этим конкретным примером я бы, вероятно, сделал:

 def sum(a: int, b: int) -> int:
    """Does exactly what it says."""
    return a   b

Поскольку параметры равны двум int s, результат — другой int , а имя функции — sum это совершенно обычное английское слово, которое означает «то, что вы получаете, когда добавляете другие вещи вместе», я не думаю, что требуется какое-либо дальнейшее объяснение (кроме, возможно, подтверждения того, что это не тактрюк).

Метки: