Материал подготовлен командой Simple-Server для администраторов VPS и выделенных серверов. Команды и пути проверяйте на тестовой машине перед production.
Кратко о задаче
В разных языках программирования у комментариев разный синтаксис. Часто это двойной слеш (//). В Python 3 комментарии в коде начинаются со знака «#». Например:
#Код выводит в консоль строку "Hello, World!"
print("Hello, World!")Также комментарий можно разместить прямо в строке с кодом:
print("Hello, World!") #Код выводит в консоль строку "Hello, World!"Комментарии должны быть полезны для читателя. Например, такой комментарий не принесет пользы:
#что-то этот код явно делает
print("Hello, World!")Хороший комментарий должен объяснять или описывать код, его цели. А некоторые разработчики считают, что комментарии должны описывать намерения программиста. В целом, будет правильным воспринимать комментарии как своеобразную документацию к коду. Если они бесполезны, то их стоит удалить.
Также в виде комментария можно оформить часть кода, чтобы она не выполнялась. Это может быть полезно при тестировании и отладке кода.
Предположим, нам нужно закомментировать такой код:
db_lp = sqlite3.connect('login_password.db')
cursor_db = db_lp.cursor()
sql_create = '''CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);'''
cursor_db.execute(sql_create)
db_lp.commit()
cursor_db.close()
db_lp.close()Это, кстати, код из нашего туториала по созданию веб-приложения с помощью Flask. Прочитать его можно здесь. Цель комментирования — сделать этот блок кода понятным. Его можно закомментировать таким образом:
db_lp = sqlite3.connect('login_password.db') #Создаем базу данных login_password
cursor_db = db_lp.cursor() #Объект класса Cursor для выполнения SQL-запросов
#SQL-запрос для создания таблицы password в базе данных
sql_create = '''CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);'''
cursor_db.execute(sql_create) #Выполняем запрос sql_create
db_lp.commit() #Подтверждаем изменения
#Закрываем Cursor и базу данных
cursor_db.close()
db_lp.close()Иногда вручную комментирование кода Python неудобно. Чтобы оформить блок кода в виде однострочных комментариев, можно использовать горячие клавиши для комментирования кода Python:
- PyCharm: Ctrl + /;
- Visual Studio Code: чтобы закомментировать/раскомментировать строку Ctrl + /, чтобы блок кода – Shift + Alt + A;
- Eclipse: чтобы закомментировать/раскомментировать строку Ctrl + /, чтобы блок кода – Ctrl + Shift + /;
- Visual Studio: Ctrl + K затем Ctrl + C, чтобы закомментировать блок кода, и Ctrl + K затем Ctrl + U, чтобы раскомментировать блок кода.
Docstring — это строковый литерал, который размещается сразу после объявления модуля, функции, класса и других структур. Это удобный способ документирования кода, к которому можно обращаться. Docstring появился в Python в 2001 году и описан в PEP 257.
Развитие языка Python происходит по четко регламентированному процессу создания, обсуждения, отбора и реализации документов PEP (Python Enhancement Proposal). В PEP размещаются предложения по развитию языка: внедрению новых функций, изменению существующих и т.п. Одним из самых известных (и полезных) документов PEP является PEP 8 — в нем отображен свод рекомендаций и соглашений по написанию кода на Python. Если вы планируете писать на Python, то вам стоит ознакомиться с этим соглашением. Правил довольно много, и для их соблюдения существуют специальные инструменты. Некоторые полезные инструменты вы сможете найти чуть ниже.
Вернемся в Docstring. Docstring — первая инструкция в объявлении объекта. Вот пример:
def function (x,y,z):
""" Docstring этой функции"""
def inner_function ():
""" Docstring вложенной функции """Синтаксис Docstring — это три кавычки в начале и в конце. Также можно использовать вместо кавычек апострофы и не три, а два или один символ. Но PEP 257 рекомендует использовать именно три кавычки.
К docstring объекта можно обратиться с помощью метода doc:
def subtraction (a,b):
"""Функция вычитает из числа a число b"""
return (a-b)
print(subtraction.__doc__)Результат: функция вычитает из числа a число b.
Также свойство doc можно использовать для получения информации о встроенных методах Python, например print:
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.Строковые литералы, встречающиеся где-то в коде Python, также могут выполнять роль документации. Они не будут распознаны компилятором байт-кода Python и не будут доступны во время выполнения программы с помощью свойства doc . Но есть два дополнительных типа docstring, которые могут быть извлечены из кода программными инструментами.
Additional docstring — это строковые литералы, которые игнорируются компилятором Python, но при этом распознаются средствами Docutils. Они размещаются сразу после docstring. Вот пример:
def function(arg):
"""Это docstring этой функции. Он будет доступен с помощью свойства __doc__."""
"""
Это additional docstring, он будет проигнорирован компилятором, но распознан Docutils.
"""
passAttribute docstring — это строковые литералы, которые встречаются сразу после простого присваивания на уровне модуля, класса или метода init. Например:
def f(x):
"""Это docstring этой функции. Он будет доступен с помощью свойства __doc__"""
return x**2
f.a = 1
""" Это attribute docstring для атрибута функции f.a, он будет проигнорирован компилятором, но распознан Docutils."""Вот основные рекомендации из PEP 257 по использованию docstring:
- После всех docstring оставляйте пустую строку.
- Docstring скрипта должен представлять собой сообщение "о правильном использовании", который, возможно, будет выведен пользователю при вызове скрипта с неправильными аргументами. Docstring должен описывать функционал, синтаксис параметров, переменные среды и используемые файлы.
- Docstring модуля должен содержать список важных объектов и однострочное пояснение для каждого из них.
- Docstring функции или метода должен описывать поведение, аргументы, return, возможные исключения и ограничения работы.
- Docstring класса должен содержать методы, переменные экземпляра и описывать поведение класса.
- Конструктор класса должен иметь свою отдельную документационную строку для метода init.
- Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия.
Нужен сервер для практики? Арендуйте VPS/VDS в России — root-доступ, NVMe, DDoS-защита и поддержка 24/7.