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

Комментарии иногда могут помочь прояснить ваш код. В Python есть три типа комментариев (не официально, но фактически): блочные, встроенные и многострочные.

“Блочный комментарий”:

Скачивайте книги ТОЛЬКО на русском языке у нас в телеграм канале: PythonBooksRU

# Multiply savings by the annual interest rate
savings = savings * 1.02

“Встроенный комментарий”:

savings = savings * 1.02 # Multiply savings by the annual interest rate

“Многострочный комментарий” (использование docstrings не по назначению):

'''
This here
is a longer
multi-line comment
also known as docstring.
'''
print("Yay")

Комментирование кода в Python

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

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

Давайте посмотрим на пример такого кода. Он реализует одномерное случайное блуждание. Как видите, код пестрит поясняющими комментариями.

import numpy as np
import random

def randwlk1d(n):
    x, y = 0, 0
    # Generate the time points (tps) [1, 2, 3, ... , n]
    tps = np.arange(n + 1)
    
    # Initialize positions array ps to the starting point y
    ps = [y]
    
    # Specify directions up and down (U and D)
    ds = ["U", "D"]
    for i in range(1, n + 1):
        # Randomly select either U or D (up or down)
        s = random.choice(ds)
        
        # Move the object up (U) or down (D)
        if s == "U":
            y += 1
        elif s == "D":
            y -= 1
        # Add each position to the ps list to track the positions
        ps.append(y)
        
    # Return timepoints and positions as (tps, ps)
    return tps, ps

Но что, если вместо комментариев к коду мы просто будем использовать более понятные имена переменных?

import numpy as np
import random

def randomwalk1D(n):
    x, y = 0, 0
    timepoints = np.arange(n + 1)
    positions = [y]
    directions = ["UP", "DOWN"]
    
    for i in range(1, n + 1):
        step = random.choice(directions)
        
        if step == "UP":
            y += 1
        elif step == "DOWN":
            y -= 1
            
        positions.append(y)
        
    return timepoints, positions

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

Однако иногда полезно иметь возможность комментировать код. Итак, давайте посмотрим, какие виды комментариев существуют в Python.

Комментарии в Python и их типы

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

Одна строка перед кодом.
В конце строки кода на той же линии.
На нескольких строках с использованием тройных кавычек.

Вот неофициальные названия этих трех типов комментариев:

Блочные комментарии
Встроенные комментарии
Многострочные комментарии или Docstrings.

Давайте рассмотрим каждый тип комментариев подробнее.

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

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

Пример блочного комментария:

# Multiply savings by the annual interest rate
savings = savings * 1.02

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

Встроенный комментарий – это комментарий на той же строке, что и код. Хотя это такой же комментарий, как и любой другой, разработчики называют его inline-комментарием.

Пример встроенного комментария:

savings = savings * 1.02 # Multiply savings by the annual interest rate

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

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

Примечание редакции: о создании многострочных строк и использовании тройных кавычек читайте в статье “Многострочная строка в Python”.

Но на самом деле многострочный комментарий не предназначен для использования в качестве собственно комментария. Вместо этого он используется как строка документации. В Python есть встроенная функция help(), которую можно вызвать для любого объекта Python. Если в этом объекте есть строка документации, функция help() покажет ее в консоли. Это может сэкономить вам время на погружение в документацию.

Например:

def greet(name):
    """ Greets a person with their name. """
    print(f"Hello, {name}")

Теперь вы можете вызвать help() для метода greet() в любом месте, где он доступен:

help(greet)

Вывод:

Help on function greet in module __main__:

greet(name)
    Greets a person with their name.

Под капотом docstring – это строковый литерал, который не игнорируется интерпретатором Python благодаря функции help(). Таким образом, docstring не может быть классифицирована как комментарий к коду. Вы без проблем можете использовать ее для комментирования кода, но это противоречит лучшим практикам.

Заключение

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

Если вам нужно добавить многострочные комментарии, следует использовать последовательные операторы #. Это связано с тем, что в Python нет многострочных комментариев. Халтурным способом добавления многострочных комментариев является использование docstring (строка в тройных кавычках), которая предназначена для документирования кода.

Перевод статьи Artturi Jalli “Comments in Python”