Комментарии и документация кода

Введение

Примеры

  • Однострочные, встроенные и многострочные комментарии

    Комментарии используются для объяснения кода, когда сам основной код неясен.

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

    Однострочные комментарии начинаются с хэш - символом ( # ) и заканчиваются в конце строки.

    • Однострочный комментарий:
     # This is a single line comment in Python
    
     
    • Встроенный комментарий:
     print("Hello World")  # This line prints "Hello World"
    
     
    • Комментарии охватывающих несколько строк есть """ или ''' . На обоих концах Это то же самое , как многострочные строки, но они могут быть использованы в качестве комментариев:

     """
    This type of comment spans multiple lines.
    These are mostly used for documentation of functions, classes and modules.
    """ 
  • Программный доступ к строкам документов

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

    Пример функции

     def func():
        """This is a function that does nothing at all"""
        return
    
     

    Строка документации можно получить с помощью __doc__ атрибута:

     print(func.__doc__)
    
     

    Эта функция вообще ничего не делает

     help(func)
    
     

    Справка по функции func в модуле __main__ :

    func()

    Эта функция вообще ничего не делает

    Еще один пример функции

    function.__doc__ только фактическая строка документации в виде строки, в то время как help функция предоставляет общую информацию о функции, включая строку документации. Вот более полезный пример:

     def greet(name, greeting="Hello"):
        """Print a greeting to the user `name`
    
        Optional parameter `greeting` can change what they're greeted with."""
    
        print("{} {}".format(greeting, name))
     

    помощь (приветствовать)

    Справка по функции greet в модуле __main__ :

    greet(name, greeting='Hello')

    Печать приветствие пользователя name \ Необязательный параметр greeting может изменить то , что они встречали с.

    Преимущества строк документации перед обычными комментариями

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

     def greet(name, greeting="Hello"):
        # Print a greeting to the user `name`
        # Optional parameter `greeting` can change what they're greeted with.
    
        print("{} {}".format(greeting, name))
     

    печать (здороваться. документ)

    Никто

     help(greet)
    
     

    Справка по функции здороваться в модуле основной:

    greet(name, greeting='Hello')

  • Написать документацию, используя строки документации

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

     def hello(name):
        """Greet someone.
    
        Print a greeting ("Hello") for the person with the given name.
        """
    
        print("Hello "+name)
     
     class Greeter:
        """An object used to greet people.
    
        It contains multiple greeting functions for several languages
        and times of the  day.
        """
    
     

    Значение строки документации можно получить доступ в программе и - например - используется в help команде.

    Синтаксические соглашения

    ОПТОСОЗ 257

    PEP 257 определяет стандарт синтаксиса для комментариев строки документации. Это в основном позволяет два типа:

    • Однострочные строки документов:

    Согласно PEP 257 они должны использоваться с короткими и простыми функциями. Все помещается в одну строку, например:

     def hello():
        """Say hello to your friends."""
        print("Hello my friends!")
    
     

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

    • Многострочные строки документов:

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

     def hello(name, language="en"):
        """Say hello to a person.
    
        Arguments:
        name: the name of the person
        language: the language in which the person should be greeted
        """
    
        print(greeting[language]+" "+name)
    
     

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

    Примечание PEP 257 определяет , какая информация должна быть предоставлена в строку документации, она не определяет , в каком формате она должна быть предоставлена. Это послужило причиной для других партий и документации разборе инструментов указать свои собственные стандарты в отношении документации, некоторые из которых перечислены ниже , и в этом вопросе .

    сфинкс

    Sphinx является инструментом для генерации HTML на основе документации для проектов , основанных на Python строки документации. Его язык разметки используется ReStructuredText . Они определяют свои собственные стандарты в отношении документации, pythonhosted.org Саваофа очень хорошее описание их . Формат сфинкса представляет собой, например , используемую PyCharm IDE .

    Функция будет документирована следующим образом в формате Sphinx / reStructuredText:

     def hello(name, language="en"):
        """Say hello to a person.
    
        :param name: the name of the person
        :type name: str
        :param language: the language in which the person should be greeted
        :type language: str
        :return: a number
        :rtype: int
        """
    
        print(greeting[language]+" "+name)
        return 4
    
     
    Руководство по стилю Google Python

    Google опубликовал Google Python Style Guide , который определяет соглашение кодирования для Python, включая комментарии к документации. По сравнению с Sphinx / reST многие говорят, что документация в соответствии с рекомендациями Google лучше читается человеком.

    Страница pythonhosted.org упоминалось выше , также приведены некоторые примеры для хорошей документации в соответствии с Руководстве по стилю Google.

    Используя Наполеона плагин, Sphinx может также анализировать документацию в Google Style Guide-совместимый формат.

    Функция будет документирована следующим образом в формате руководства по стилю Google:

     def hello(name, language="en"):
        """Say hello to a person.
    
        Args:
            name: the name of the person as string
            language: the language code string
    
        Returns:
            A number.
        """
    
        print(greeting[language]+" "+name)
        return 4
    
     

Синтаксис

Параметры

Примечания