Разница между комментариями и строками документации в Python

В этой статье мы рассмотрим различия между комментариями и строками документации в Python.

Введение

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

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

Объявление комментариев в Python

Однострочные комментарии в Python объявляются с помощью знака # следующим образом:

# Это однострочный комментарий

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

Функция, приведенная в примере, добавляет число и его квадрат в словарь Python в качестве пары значений ключа:

# Это многострочный комментарий
# Написанный используя несколько однострочных комментариев
def add_square_to_dict(z, dict_one):
    x = z * z
    dict_one[str(z)] = x
    return dict_one

Мы также можем реализовать многострочные комментарии в Python, используя многострочные строковые константы.

Здесь многострочная строка объявляется, но не присваивается какой-либо переменной, из-за чего для нее не выделяется память, и она работает точно так же как комментарий:

"""
This is a multiline comment
written using multiline strings
"""

Вы должны иметь в виду, что комментарии, написанные с использованием знака #, не обязательно должны следовать правилам отступа, но комментарии, написанные с использованием многострочных строк, должны следовать отступу блока, в котором они объявлены.

Объявление строк документации в Python

Docstring — это строковая константа, связанная с любым объектом или модулем Python. Объект может быть классом, методом или функцией. Строка docstring записывается просто как многострочные комментарии с использованием многострочных строк, но это должен быть первый оператор в определении объекта.

Docstring для класса в Python объявляется следующим образом:

class ClassName:
    """
    Это строка документдации для текущего класс.

    Здесь должно находится описание того что делает класс и его атрибуты
    """

    def __init__(self, data):
        self.data = data

Строка документа для метода объявляется так:

class ClassName:
    """
    Это строка документдации для текущего класс.

    Здесь должно находится описание того что делает класс и его атрибуты
    """

    def __init__(self, data):
        self.data = data

    def increment(self):
        """
        Это строка документации для метода.

        В ней описывается, что делает метод, каковы его вызывающие условности и

        каковы его побочные эффекты
        """
        self.data = self.data + 1
        return self.data

Строка документа для функции объявляется так, как показано ниже:

def decrement(value):
    """Это строка документации для этой функции.

    Она описывает, что делает эта функция, каковы ее вызывающие конвенции и

    каковы его побочные эффекты
    """
    value = value - 1
    return value

Доступ к комментариям в Python

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

Доступ к строкам документов в Python

Мы можем получить доступ к docstring, связанному с любым объектом Python, используя его атрибут __doc__.

Доступ к строке документа класса можно получить с помощью className.__doc__ следующим образом:

class ClassName:
    """
    Это строка документдации для текущего класс.

    Здесь должно находится описание того что делает класс и его атрибуты
    """

    def __init__(self, data):
        self.data = data

    def increment(self):
        """
        Это строка документации для метода.

        В ней описывается, что делает метод, каковы его вызывающие условности и

        каковы его побочные эффекты
        """
        self.data = self.data + 1
        return self.data


print(ClassName.__doc__)

Вывод программы:

    Это строка документдации для текущего класс.

    Здесь должно находится описание того что делает класс и его атрибуты
    

Доступ к строке документа метода можно получить с помощью className.methodName.__doc__ вот так:

class ClassName:
    """
    Это строка документдации для текущего класс.

    Здесь должно находится описание того что делает класс и его атрибуты
    """

    def __init__(self, data):
        self.data = data

    def increment(self):
        """
        Это строка документации для метода.

        В ней описывается, что делает метод, каковы его вызывающие условности и

        каковы его побочные эффекты
        """
        self.data = self.data + 1
        return self.data


print(ClassName.increment.__doc__)

Вывод программы:

        Это строка документации для метода.

        В ней описывается, что делает метод, каковы его вызывающие условности и

        каковы его побочные эффекты
        

Доступ к docstring функции можно получить с помощью functionName.__doc__ так, как показано ниже:

def decrement(value):
    """Это строка документации для этой функции.

    Она описывает, что делает эта функция, каковы ее вызывающие конвенции и

    каковы его побочные эффекты
    """
    value = value - 1
    return value


print(decrement.__doc__)

Вывод программы:

Это строка документации для этой функции.

    Она описывает, что делает эта функция, каковы ее вызывающие конвенции и

    каковы его побочные эффекты

Цель использования комментария в Python

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

Цель использования строки документа в Python

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

Docstrings используются для связывания документации с такими объектами, как классы, методы и функции в Python, и они описывают, что делает объект.

Заключение

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