Комментарии Python – многострочные комментарии, лучшие практики

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


Как писать комментарии на Python?

  • Комментарии Python начинаются с символа # и продолжаются до конца строки.
  • Мы можем начать комментарий с начала строки, после пробелов или кода.
  • Если символ решетки присутствует в строковом литерале, он является частью строки.

Примеры комментариев Python

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

1. Комментарий для переменных

name = "Pankaj"  # employee name
id = 100  # employee id

data = "#123"  # this is comment, data contains # and that is not part of the comment.

2. Комментарии к функциям

# This function adds the two numbers
def add(x, y):
    return x+y

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

3. Комментарии к классу

# This class provides utility functions to work with Strings
class StringUtils:

    def reverse(s):
        return ''.join(reversed(s))

Блок комментариев Python или многострочный комментарий

Иногда не представляется возможным разместить комментарий в одну строку. В этом случае мы можем создать блок комментариев или разбить комментарий на несколько строк. Нам нужно добавить к каждой строке префикс в виде решетки (#), чтобы написать многострочный комментарий.

# This class provides utility functions to work with Strings
# 1. reverse(s): returns the reverse of the input string
# 2. print(s): prints the string representation of the input object
class StringUtils:

    def reverse(s):
        return ''.join(reversed(s))
    
    def print(s):
        print(s)

Многострочный комментарий Python


Использование Python Docstring в качестве многострочного комментария

Строки документации Python (Docstring) используются для предоставления документации для функций, классов и модулей. Они определяются между парой тройных двойных кавычек («”»). Они должны быть определены сразу под объявлением функции или класса.

Давайте кратко рассмотрим несколько примеров строк документации Python.

def foo():
    """The foo() function needs to be implemented.
    Currently, this function does nothing."""
    pass


class Data:
    """ This class is used to hold Data objects information."""

Мы можем получить доступ к строке документации сущности, используя атрибут __doc__.

print(foo.__doc__)
print(Data.__doc__)

Строки документации Python


Стоит ли использовать Docstring для указания длинных многострочных комментариев?

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


Многострочная строка Python как многострочные комментарии

Мы также можем использовать многострочные строки как многострочные комментарии. Согласно этому твиту Гвидо, они не генерируют никакого кода.

'''
This function read employees data from the database
emp_id: employee id, should be int
returns employee object.
'''
def read_emp_from_db(emp_id):
    i = int(emp_id)
    '''code to read emp data
    using the employee unique id number'''
    pass

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


Лучшие практики комментирования Python

  • Всегда предоставляйте содержательные комментарии, определяющие использование сущности.
  • Длинный комментарий лучше разбить на несколько строк.
  • Не грубите в комментариях.
  • Придерживайтесь сути комментариев. Никто не хочет читать роман в комментариях к коду.
  • Избегайте бесполезных комментариев, которые не несут никакой полезной информации. Ниже приведены некоторые примеры бесполезных комментариев.
# count variable
count = 10

# foo() function
def foo():
    pass
  • Иногда комментарии не нужны. Достаточно иметь правильное имя самой сущности. Давайте рассмотрим пример этого сценария.
# This function add two numbers
def foo(x, y):
    return x+y


# Better to have function defined as below. There is no use of comments.

def add_two_numbers(x, y):
    return x+y
  • Всегда полезно иметь систему комментирования. При работе с большим количеством членов команды и несколькими проектами в организации рекомендуется использовать политику комментирования. Например, вы можете определить политику комментирования следующим образом:
# {Object Type} - {Usage}
# Data Object - stores the Data fetched from the database
data_obj = Data()


# {Function Short Description}
# {Input Arguments and their types}
# {Return object details}
# {Exception Details}

# This function adds all the elements in the sequence or iterable
# numbers: sequence or iterable, all the elements must be numbers
# Returns the sum of all the numbers in the sequence or iterable
# Throws ArithmeticError if any of the element is not a number


def add_numbers(numbers):
    sum_numbers = 0
    for num in numbers:
        sum_numbers += num
    return sum_numbers

Сочетание клавиш Python Comment для комментирования блока

Если вы работаете с Python IDE или Jupyter Notebook, вы можете использовать сочетание клавиш, чтобы закомментировать блок кода.

  • Сочетание клавиш для комментариев в macOS – выберите строки, которые вы хотите прокомментировать, и нажмите Command+/, и он автоматически добавит # в начало каждой строки, чтобы превратить их в блок комментариев. Если это пустая строка, он добавит # в начало строки, и вы сможете написать комментарий.
  • Сочетание клавиш для комментариев в Windows и Linux — используйте сочетание клавиш Ctrl+/, чтобы превратить блок кода в комментарий.

Краткое содержание

  • Система комментариев Python проста и всегда начинается с символа #.
  • Python docstring используется для документации. Не следует злоупотреблять им для многострочных комментариев.
  • Для многострочных комментариев начинайте каждую строку с символа решетки.
  • Следуйте рекомендациям по добавлению комментариев в программу.
  • При работе с большим количеством членов команды всегда полезно иметь политику комментирования.

Автор

Фото аватара

Владимир Михайлов

Программист на Python с большим количеством опыта и разнообразных проектов.