Строки документации – одна строка против нескольких строк

StackOverflow https://stackoverflow.com/questions/9392096

  •  29-10-2019
  •  | 
  •  

Вопрос

добавляю немного (эпидок) документации к пакету, который я написал, и я сталкиваюсь с множеством случаев, когда повторяюсь множество раз. 

def script_running(self, script):
    """Return if script is running

    @param script: Script to check whether running

    @return: B{True} if script is running, B{False} otherwise
    @rtype: C{bool}
    """

PEP257 Говорит, что:

Однострочники предназначены для действительно очевидных случаев.

а также

Строка документации для функции или метода должна суммировать ее поведение и документировать ее аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда ее можно вызывать (все, если применимо).

Существует ли общее руководство или стандартная практика, когда следует проводить границу между однострочным (описанием) и полными полями параметров/возврата?

Или при создании документации я должен включать все применимые поля для каждой функции, независимо от того, насколько повторяющимися они кажутся?

Бонусный вопрос:Синтаксически, как лучше всего описать script параметр?

Это было полезно?

Решение

Общее руководство, которое вы ищете, находится прямо в PEP257 в том, что вы процитировали, возможно, вам просто нужно увидеть это в действии.

Ваша функция является хорошим кандидатом на однострочную строку документации («действительно очевидные случаи»):

def script_running(self, script):
    """Check if the script is running."""

Обычно, если вы говорите, что функция что-то проверяет, это означает, что она собирается вернуть результат. True или False, но если хотите, можете быть более конкретным:

def script_running(self, script):
    """Return True if the script is running, False otherwise."""

Еще раз все в одну строку.

Я бы, наверное, еще поменял название вашей функции, потому что в ее названии (скрипте) нет необходимости подчеркивать, что именно функция делает.Имя функции должно быть приятным, коротким и информативным о том, что делает функция.Пожалуй, я выберу:

def check_running(self, script):
    """Return True if the script is running, False otherwise."""

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

Для многострочного примера позвольте мне позаимствовать строку документации из рекомендации Google:

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

Это может быть один из способов «подведите итоги его поведения и задокументируйте его аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда его можно вызывать (все, если применимо)».

Возможно, вам также будет интересно посмотреть на это пример проекта pypi что это должно быть задокументировано с помощью Сфинкс.

Мои 2 цента: Методические рекомендации призваны дать вам представление о том, что вам следует и не следует делать, но они это не строгие правила которому нужно слепо следовать.Итак, в конце выберите то, что вы считаете лучшим.

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

ПЭП8 говорит тебе «Ограничить все строки максимум 79 символами» хотя в конце концов все делают 80.

Это 80 символов:

--------------------------------------------------------------------------------

И это может быть крайний случай, когда вам действительно нужно одно немного длинное предложение:

def my_long_doc_function(arg1, arg2):
    """This docstring is long, it's a little looonger than the 80 charachters
    limit.

    """

Это похоже на однострочную строку документации, что означает, что для действительно очевидных случаев, но в вашем редакторе (с ограничением в 80 символов) он состоит из нескольких строк.

Другие советы

Я думаю, что при добавлении расширенного синтаксиса для строк документации, вероятно, всегда присутствует некоторая степень повторения, т.е.разметка epydoc/sphinx.

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

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top