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

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

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

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

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

К о м м е н т а р и й к | | П е р е м е н н ы е

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

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

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

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

К о м м е н т а р и и д л я к л а с с а

# 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 Docstring как многоугольный комментарий

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

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

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."""

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

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

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

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

Python Multiline String в виде многостроительных комментариев

Мы также можем использовать многослойную строку как многоуровневые комментарии. По словам Гвидо Tweet они не генерируют код.

'''
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 проста и всегда начинается с #.
Python Docstring предназначен для документирования. Вы не должны неправильно использовать это для многоуровневых комментариев.
Начните каждую строку с персонажем хеша для многострочных комментариев.
Следуйте от лучших практик для добавления комментариев в программе.
Наличие комментирующей политики на месте – это всегда хорошая идея при работе со многими членами команды.

Использованная литература:

P y t h o n . o r g D o c s .