Комментарии к коду python

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

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

# 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 нет ни многострочных, ни встроенных комментариев. Однако есть три часто используемых способа их добавления:

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

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

1. Блочные комментарии
2. Встроенные комментарии
3. Многострочные комментарии или 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, ")

Теперь вы можете вызвать 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”

Источник

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

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

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

Хорошие против плохих комментариев

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

Например, это довольно бесполезный комментарий:

b = 56 # assigning b a value of 56

Следующий пример демонстрирует более полезный комментарий и дает переменным очевидные имена:

salestax10 = 1.10 # defining a sales tax of 10% salestax20 = 1.20 # defining a sales tax of 20%

Существует бесконечное количество других сценариев, которые заслуживают комментариев. Это только один пример. Хорошее практическое правило — добавлять комментарии к любой строке кода (например, к списку) или к фрагменту кода, цель которого не очевидна. Это очень субъективно, и на самом деле это навык, который необходимо изучить.

Типы комментариев

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

В следующих разделах я опишу каждый тип комментария.

Однострочные комментарии

Такой комментарий начинается с хеш-символа ( # ) и сопровождается текстом, который содержит дополнительные пояснения.

# defining the post code postCode = 75000

Вы также можете написать комментарий рядом с оператором кода. Следующий пример показывает, это:

# define the general structure of the product with default values product =

Руководство по стилю для кода Python ( PEP8 ) рекомендует менее 79 символов на строку. На практике 70 или 72 символа в строке легче читать, и поэтому рекомендуется. Если ваш комментарий приближается к этой длине или превышает ее, тогда вы захотите распределить его по нескольким строкам.

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

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

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

Версия 1 объединяет однострочные комментарии следующим образом:

# LinuxThingy version 1.6.5 # # Parameters: # # -t (--text): show the text interface # -h (--help): display this help

Версия 2 проще, чем версия 1. Изначально она предназначалась для создания документации (подробнее об этом ниже), но ее также можно использовать для многострочных комментариев.

""" LinuxThingy version 1.6.5 Parameters: -t (--text): show the text interface -h (--help): display this help """

Обратите внимание, что последняя версия должна быть заключена в специальные кавычки ( «»» ) для работы, а не хеш-символы.

Обычная практика

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

Этот фрагмент взят из одного из примеров, которые я использую в учебных целях. Комментарий начинается с описания, за ним следует уведомление об авторских правах с моим именем и год публикации кода. Ниже вы увидите, что код лицензирован под GNU Public License ( GPL ). Для того, чтобы связаться со мной, мой адрес электронной почты также добавлен туда.

# ----------------------------------------------------------- # demonstrates how to write ms excel files using python-openpyxl # # (C) 2015 Frank Hofmann, Berlin, Germany # Released under GNU Public License (GPL) # email frank.hofmann@efho.de # -----------------------------------------------------------

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

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

Строка документа — это либо однострочный, либо многострочный комментарий. В последнем случае первая строка является кратким описанием, а после первой строки следует пустая строка.

Начните строку документа с заглавной буквы и завершите ее точкой.

Это основной пример того, как это выглядит:

def add(value1, value2): """Calculate the sum of value1 and value2.""" return value1 + value2

В интерактивной справочной системе Python строка документации становится доступной через атрибут __doc__ .

>>> print add.__doc__ Calculate the sum of value1 and value2.

Существует ряд инструментов, которые автоматически генерируют документацию из строк документации, таких как Doxygen, PyDoc, pdoc и расширение autodoc для Sphinx. Мы объясним вам, как работать с ними в следующей статье.

Заключение

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

Источник