«Хороший код — это самодокументируемый код». Вы слышали эту фразу раньше? Я тоже. Более чем за 20 лет написания кода я слышал эту фразу чаще других. Это уже клише.
У этой фразы, как и у многих других клише, есть доля правды. Но смысл этого предложения давно потерялся, многие люди уже не понимают, что значит это выражение из-за постоянного и повсеместного использования.
В этой статье мы рассмотрим хорошие, плохие и отвратительные примеры комментирования в коде.
Начинающие разработчики должны помнить, что существует два типа комментариев в коде: поясняющие и документационные.
Документационные комментарии
Документационные комментарии предназначены для всех, кто когда-либо будет использовать ваш исходный код, но вряд ли сможет понять или прочитать его правильно. Если вы создаёте библиотеку или фреймворк, которые будут использоваться другими разработчиками, то вам нужно будет разработать документацию для API.
Специалист техподдержки 1С АО «Гринатом» , , можно удалённо , По итогам собеседования
Как оставить комментарий на Ютубе?
Чем больше API-документация отдалена от вашего кода, тем больше вероятность того, что она станет неточной или устаревшей с течением времени. Хорошим способом преодоления этой проблемы является документирование в самом коде. Таким образом вы сможете извлечь документацию с помощью специальных инструментов.
Посмотрите на пример кода из Lodash — популярной библиотеки для JavaScript:
Если вы сравните эти комментарии с онлайн-документацией, то увидите, что они одинаковы. При написании документационных комментариев убедитесь, что они соответствуют общепринятому стандарту и что они отличаются от уточняющих и поясняющих комментариев в самом коде. Некоторые популярные инструменты и стандарты включают использование JSDoc для JavaScript, DocFx для .Net и JavaDoc для Java.
Недостатком этих комментариев можно назвать лишний шум в коде, который они создают. Этот шум создаёт сложности при чтении кода другими разработчиками, участвующих в его разработке и поддержании.
Однако в большинстве современных редакторов есть возможность скрыть комментарии, чтобы лучше сосредоточиться на редактировании кода.
Поясняющие комментарии
Поясняющие комментарии предназначаются для всех (включая вас в будущем), кто будет заниматься поддержкой, рефакторингом и расширением вашего кода.
Зачастую уточняющий комментарий к вашему коду является его отражением. По пояснению можно судить нагружен ваш код или нет. Следует пытаться удалять пояснения в коде, упрощая его, ведь «хороший код — самодокументированный код».
Приведу пример плохого, но забавного пояснения:
/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis. **/ $str = str_replace(array(«»),» «,$str);
Вместо того, чтобы писать амфибрахий для украшения запутанного кода, автор мог бы с пользой потратить время и поработать над функцией, облегчив чтение и понимание кода.
Поймите меня правильно, бывают моменты, когда небольшая порция юмора помогает расслабиться, особенно когда вы просто утопаете в работе. Но не пишите забавный комментарий, чтобы приукрасить плохой код. Именно из-за таких шуток в будущем мало кто захочет исправлять код и заниматься его рефакторингом.
Как написать комментарии в программе.
Вам действительно хочется приукрасить рифмой свой плохой код, чтобы кодеры ухмыльнулись и проигнорировали его, двигаясь дальше?
Также бывают случаи, когда авторы добавляют излишние пояснения. Например, если код очень прост и понятен любому, то нет необходимости добавлять пояснения.
Не совершайте подобные глупости:
/* Устанавливает значение 32 для переменной age */ int age = 32;
Тем не менее, бывают случаи, когда поясняющие комментарии нужны, вне зависимости от того, как выглядит ваш код.
Обычно это происходит, когда вам нужно добавить контекст к неинтуитивному решению.
Вот хороший пример из фреймворка Lodash:
function addSetEntry(set, value) < /* Не возвращать `set.add`, потому что эта цепочка вызовов не сработает в IE 11. */ set.add(value); return set; >
Иногда бывают случаи, когда оказывается, что на первый взгляд наивное решение проблемы является наилучшим после долгих экспериментов и размышлений. В подобных моментах почти неизбежна ситуация, когда другой разработчик, подумав, что он умнее, чем вы, начнёт копаться в коде, но в итоге выяснит, что ваше решение всё это время оставалось лучшим.
А иногда тем самым «более умным» кодером можете оказаться вы сами. Поэтому в таких случаях лучше оставлять комментарии к коду, чтобы в будущем сэкономить своё и чужое время и нервы.
Комментарий снизу полностью отражает суть мысли выше:
/** Уважаемый разработчик: Как только ты прекратишь пытаться «оптимизировать» этот код и поймёшь, какую ошибку ты допустил взявшись за это дело, пожалуйста, увеличь номер на счётчике ниже для следующего разработчика: количество_часов_потрачено_впустую_здесь = 42 **/
Опять же, комментарий сверху содержит больше юмора, чем пользы. Вам СЛЕДУЕТ оставлять комментарии, предупреждающие других от поиска какого-либо «лучшего решения», если вы сами уже пытались это сделать, но ничего хорошего из этого не вышло. В комментарии следует указать, какое решение вы пытались найти и почему вы решили, что оно не подходит в данной ситуации или не работает.
/* не используйте глобальную функцию isFinite(), потому что она возвращает true для нулевых значений */ Number.isFinite(value)
Отвратительные комментарии
№28 Как писать комментарии / для начинающих
Добавление комментариев считается хорошей практикой. Это неисполняемые, но все равно важные части кода. Они не только помогают программистам, работающим над одним и тем же проектом, но также тестировщикам, которые могут обращаться к ним для ясности при тестировании белого ящика.
Куда лучше добавлять комментарии при создании или обновлении программы, иначе можно утратить контекст. Комментарии, добавленные позже, могут быть далеко не настолько эффективными.
Комментарии — это способ выражения того, что делает программа на самом высоком уровне. Это отмеченные строчки, которые комментируют код. В Python они бывают двух типов: одно- и многострочные.
Однострочные комментарии в Python
Такой тип комментариев нужен для написания простых, быстрых комментариев во время отладки. Такие комментарии начинаются с символа решетки # и автоматически заканчиваются символом окончания строки (EOL).
# Хороший код документируется print(«Изучите Python шаг за шагом!»)
При добавлении комментария важно убедиться, что у него тот же уровень отступа, что и у кода под ним. Например, нужно оставить комментарий к строке объявления функции, у которой нет отступа. Однако они имеются у блоков кода внутри нее. Поэтому учитывайте выравнивание при комментировании внутренних блоков кода.
# Создадим список месяцев
months = [‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’, ‘May’, ‘Jun’,
‘Jul’,’Aug’,’Sep’,’Oct’,’Nov’,’Dec’]
# Функция вывода календарных месяцев
def showCalender(months):
# Цикл for проходит по списку и вводит название каждого месяца
for month in months:
print(month)
showCalender(months)
Многострочные комментарии в Python
Python позволяет писать комментарии на нескольких строках. Они называются многострочными или блочными. Такой тип комментирования подходит для описания чего-то более сложного.
Этот тип комментариев нужен для описания всего последующего кода. Дальше примеры многострочных комментариев в Python.
С помощью символа #
Для добавления многострочного комментария нужно начинать каждую строку с символа решетки и одного пробела. Такой комментарий можно разбить на абзацы. Для этого достаточно добавлять пустые строки с символом перед каждым из них.
Примечание: в оригинале этот символ (#) называется octothorpe, что переводится с латинского как «восемь концов». Термин придумала группа инженеров в Bell Labs, которая работала над проектом первой сенсорной клавиатуры.
# Чтобы выучить любой язык, вы должны следовать этим правилам.
# 1. Знать синтаксис, типы данных, структуры и условные операторы.
# 2. Изучить обработку ошибок и ввод/вывод.
# 3. Читайте о продвинутых структурах данных.
# 4. Пишите функции и следуйте концепциям ООП.
def main():
print(«Начнем изучать Python.»)
Docstring в Python
В Python есть такая особенность, как задокументированные строки (docstring). С их помощью программисты могут быстро добавлять комментарии для каждого модуля, функции, метода или класса в Python.
Задать docstring можно с помощью строковой константы. Она обязана быть первой инструкцией в определении объекта.
У docstring более широкая область применения, чем у комментария. Она должна описывать, что делает функция, а не как. Хорошей практикой считается добавление таких строк в каждую функцию программы.
Как задать docstring в Python?
Задать docstring в Python можно с помощью тройных кавычек Нужно добавить один набор в начале и еще один – в конце. Docstring также могут занимать по несколько строк.
Примечание: строки с тремя кавычками также являются docstring в Python, пусть они и могут казаться обычными комментариями.
В чем отличие между комментарием и docstring?
Строки, начинающиеся с тройной кавычки, — это все еще обычные строки, которые могут быть написаны в несколько строк. Это значит, что они все еще являются исполняемыми инструкциями. Если же у них нет метки, значит сборщик мусора уничтожит их после исполнения.
Интерпретатор Python не будет игнорировать их так же, как комментарии. Но если такая строка расположена сразу же после объявления функции или класса в верхней части модуля, то она станет docstring. Получить к ним доступ можно следующим образом — myobj.__doc__ .
def theFunction():
»’
Эта функция демонстрирует использование docstring в Python.
»’
print(«docstring python не являются комментариями.»)
print(«nВыведем docstring функции. «)
print(theFunction.__doc__)
Выводы
Комментарии и docstring добавляют ценности программе. Они делают программы более читаемыми и пригодными для последующей поддержки. Даже при рефакторинге сделать это будет намного проще с комментариями.
Разработка программного обеспечения — это лишь на 10% написание кода. Остальные 90% — поддержка.
Поэтому всегда добавляйте осмысленные комментарии и docstring, потому что они упрощают процесс взаимодействия и ускоряют процесс рефакторинга.
Источник: pythonru.com
Лучшие практики написания комментариев к коду
Известный профессор МТИ Гарольд Абельсон сказал: «Программы нужно писать для того, чтобы их читали люди, и лишь случайно — чтобы их исполняли машины». Хотя он намеренно преуменьшил важность исполнения кода, однако подчёркивает, что у программ две важные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и с одинаковой лёгкостью воспринимают все синтаксически корректные программы. У людей всё иначе. Одни программы нам воспринимать легче, чем другие, и мы ищем комментарии, которые помогут нам разобраться.
Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.
Как писал Питер Фогель:
- Написание и поддержка комментариев требует усилий.
- Ваш компилятор не смотрит на комментарии, поэтому невозможно определить их корректность.
- С другой стороны, вы гарантируете, что компьютер делает именно то, что предписывает ваш код.
Первое правило: комментарии не должны дублировать код
Многие начинающие программисты пишут слишком много комментариев, потому что их к этому приучили. Я видел, как старшекурсники на факультете информатики добавляют комментарии к каждой закрывающей скобке, чтобы показать закрытие блока:
if (x > 3) < … >// if
Я слышал о преподавателях, которые требуют от студентов комментировать каждую строку кода. Для совсем новичков это может быть оправдано, однако такие комментарии как боковые колёсики на детском велосипеде, которые по мере роста надо снять.
Неинформативные комментарии вредны, потому что:
- вносят визуальный беспорядок;
- отнимают время на написание и чтение;
- могут устареть.
i = i + 1; // Add one to i
Комментарий не добавляет полезной информации и требует усилий по поддержке.
Требования комментировать каждую строку справедливо высмеяли на Reddit:
// create a for loop //
Второе правило: хорошие комментарии не оправдывают непонятный код
Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:
private static Node getBestChildNode(Node node) < Node n; // best child node candidate for (Node node: node.getChildren()) < // update n if the current state is better if (n == null || utility(node) >utility(n)) < n = node; >> return n; >
Комментарий был бы не нужен, если дать переменной правильное название:
private static Node getBestChildNode(Node node) < Node bestNode; for (Node currentNode: node.getChildren()) < if (bestNode == null || utility(currentNode) >utility(bestNode)) < bestNode = currentNode; >> return bestNode; >
Как написали Керниган и Плогер в книге «The Elements of Programming Style»: «Не комментируйте плохой код, а переписывайте его».
Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде
Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:
Отладка вдвое труднее первоначального написания кода. Поэтому если вы пишете код как можно умнее, то вы по определению не настолько умны, чтобы его отладить.
Предупреждение читателям, чтобы они держались подальше от вашего кода, сродни включению аварийных огней: признание в том, что вы делаете что-то незаконное. Лучше перепишите код так, чтобы вы сами понимали его достаточно, чтобы объяснить другим. Или ещё лучше, чтобы его вообще не требовалось объяснять.
Четвёртое правило: комментарии должны исключать путаницу, а не вносить её
Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:
[Питер Самсон] особенно усложнял ситуацию тем, что отказывался добавлять в свой исходный код комментарии с пояснением, что он делает в каждом конкретном случае. Одна из распространённых программ, написанных Самсоном, состояла из сотен инструкций на ассемблере с единственным комментарием после инструкции под номером 1750. Комментарий был такой: RIPJSB, и люди ломали головы над тем, что это означает, пока кто-то не догадался, что в 1750-м году умер Бах, и что Самсон написал аббревиатуру фразы “Rest In Peace Johann Sebastian Bach”.
Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.
Пятое правило: объясняйте в комментариях не идиоматический код
Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):
final Object value = (new JSONTokener(jsonString)).nextValue(); // Note that JSONTokener.nextValue() may return // a value equals() to null. if (value == null || value.equals(null))
Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:
if (b == true)
Я удивился, почему бы не заменить его просто на if (b) , как сделал бы это на Java. В результате небольшого исследования я выяснил, что допускающие пустое значение булевы переменные явным образом сравниваются с true, чтобы избежать уродливой проверки на null:
if (b != null b)
Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.
Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.
Если вы такой же, как и большинство программистов, то иногда вы используете найденный в сети код. Добавляйте ссылку на исходник, чтобы будущие читатели имели полный контекст, например:
- какую задачу вы решали;
- кто предоставил код;
- почему это решение рекомендовано;
- что думали об этом комментаторы;
- работает ли это ещё;
- как его можно улучшить.
/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */
Если перейти по ссылке, то вы обнаружите, что:
- Автора кода зовут Tomáš Procházka, он входит в топ-3% на Stack Overflow.
- Один из комментаторов предложил улучшение, уже внесённое в репозиторий.
- Другой комментатор предложил способ избежать пограничного случая.
// Magical formula taken from a stackoverflow post, reputedly related to // human vision perception. return (int) (0.3 * red + 0.59 * green + 0.11 * blue);
Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.
Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.
Вы также можете ссылаться на оказавшиеся полезными руководства в качестве благодарности их авторам и ради экономии времени читателей:
// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html // for a great reference and examples.
Седьмое правило: добавляйте ссылки на внешние примеры в тех случаях, когда это полезнее всего
Конечно, не все ссылки ведут на Stack Overflow.
// http://tools.ietf.org/html/rfc4180 suggests that CSV lines // should be terminated by CRLF, hence the rn. csvStringBuilder.append(«rn»);
Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.
Восьмое правило: исправляя баги, добавляйте комментарии
Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:
Комментарий не только помогает понять код в конкретных методах, но и определить, нужен ли ещё этот код и как его тестировать. Также комментарий может ссылаться на систему отслеживания ошибок:
// Use the name as the title if the properties did not include one (issue #1425)
Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).
Девятое правило: помечайте комментариями незаконченные реализации
Иногда необходимо проверять код, даже несмотря на его ограничения. Хотя может быть заманчиво не рассказывать о недостатках своего кода, лучше сделать это явно, например, в комментарии TODO:
// TODO(hal): We are making the decimal separator be a period, // regardless of the locale of the phone. We need to think about // how to allow comma as decimal separator, which will require // updating number parsing and other places that transform numbers // to strings, such as FormatAsDecimal
Стандартный формат для таких комментариев помогает оценить и адресовать технический долг. Ещё лучше, если добавите задачу в систему отслеживания ошибок и вставите ссылку в комментарий.
Заключение
Комментарии не оправдывают и не улучшают плохой код. Они дополняют хороший код, предоставляя другой тип информации. Как писал Джефф Этвуд, один из сооснователей Stack Overflow: «Код говорит вам «как», а комментарии говорят «почему»». Следование описанным правилам сэкономит время и нервы вам и вашей команде.
- лучшие практики
- комментирование кода
- никто не читает теги
- Блог компании VK
- Программирование
- Анализ и проектирование систем
- Проектирование и рефакторинг
Источник: habr.com