как правильно комментировать код
Как правильно комментировать код
Как-то раз сидел в аудитории с ноутом около розетки, а в это время на соседней парте принимался зачет по программированию. Я не сильно вникал в суть вопросов на которые общались студент и преподаватель, назовем его Иван Ивановичем. Разговор был довольно спокойный и тихий, но у меня получилось выхватить часть. Преподаватель говорил о комментариях (видимо сдавалась программа, в которой не было ни строчки комментариев). Меня этот момент заинтересовал и я начал прислушиваться. Было замечено, что мне тоже интересно, преподаватель начал импровизированную лекцию. Ниже представлен тот небольшой кусок знаний который я тогда вынес с этой 5ти минутной лекции.
Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 2 и более программиста) и студентам будет полезно. Кроме того, все изложенные ниже советы имеют альтернативу и могут быть использованы лишь частично.
Почему я приписал сюда студентов? Они же, казалось бы, одни работают над программой на зачет! Препод, когда принимает программу, справедливо считается вторым разработчиком, который в идеале без помощи студента должен понять, что там написано и как оно работает.
Как писать код сразу с комментариями
По сути говоря, на той лекции принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:
И лишь когда готов каркас из комментариев, следует писать код который будет реализовывать то, что описано комментариями.
Как упоминалось выше, данный принцип представляет собой модифицированный принцип, хорошо зарекомендовавшего себя TDD. Тут следует понимать, что отступление от комментариев, в отличии от отступления от логики тестов, не приведет к тяжелым последствиям, ну разве что придется комментарии переписывать
Теперь представим «чисто гипотетическую» ситуацию, когда уже имеется код в 200 000 строк, написанный гениальным программистом криворуким индусом и не содержит ни строчки комментария. Однако вам необходимо, мало того что убить этого программиста понять этот код, но и сопровождать его в дальнейшем. Вы даже разобрались в этом коде, и будучи приличным человеком, решили дополнить код комментариями для, так сказать, будущих поколений. Но возникает вопрос: как?
Как комментировать уже существующий код
Как писать хорошие комментарии к коду: «зачем», а не «как»
Привет, Хабр! Представляю вашему вниманию перевод статьи «Writing good comments: the why, not the how» автора Jack Franklin.
Комментирование кода в программистской среде нередко считается пустой тратой времени или неким сигналом о том, что код можно и улучшить. Вот цитата из файла CONTRIBUTING.md, который я нашёл на Гитхабе (и таких примеров очень, очень много):
Комментариев следует избегать. Если ваш код нельзя понять без комментариев, перепишите его так, чтобы он сам себя объяснял.
У каждой строки кода должен быть комментарий, объясняющий, что она делает. Ваша работа в курсе будет оцениваться по этому критерию.
Итак, положим, вы свежеиспечённый студент, только начавший этот курс. Что вы будете делать? Комментировать код, конечно же!
Люди, говорящие, что комментарии — это плохо, на самом деле думают о таких вот комментариях. И они при этом совершенно правы! Комментарии вроде тех, что выше, отвечающие в программировании на вопрос «как?», совершенно бесполезны. Все эти комментарии не привнесли в код ничего, что нельзя понять из него самого.
Отвечайте на вопрос «зачем?»
Проблема с комментариями выше заключается в том, что они объясняют, как. Поясняют шаги, которые мы делаем в коде. Такие комментарии крайне редко оказываются полезными; код сам по себе куда лучше рассказывает о нужном порядке действий. В конце концов, строки кода — лишь инструкции, объясняющие компьютеру, как выполнить задачу.
Обычно в обилии комментариев нет никакой нужды, потому что можно написать простой код, лишённый особенностей или нюансов, которые придавали бы ему непонятный вид. Но порой возникают ситуации, когда написать элементарный и интуитивно понятный код нет возможности. Может, дело в неком баге, который приходится обходить. Или вам досталось в наследство от прошлых разработчиков счастье в виде системы, не дающей вам решить проблему так, как хотелось бы. Или, в конце концов, просто-напросто нет лёгкого способа улучшить код.
Как-то раз работал я в процессинговой компании. У нас каждый день выполнялся огромный SQL-запрос, выбиравший платежи для выплаты. Запрос был хорошо оптимизированным — нам нужно было, чтобы он работал весьма быстро — и притом крайне сложным: приходилось учитывать множество пограничных случаев. Мы очень старались, чтобы он был настолько ясным, насколько вообще возможно. Впрочем, этот запрос никогда не смог бы полноценно быть интуитивно понятным и лёгким для восприятия. Он просто содержал слишком много кода с кучей условий и логикой, понять которую можно было лишь в контексте нашей компании и того, как она работала.
Я хотел найти пример, который можно будет здесь показать, поэтому я отправился в дебри кодовой базы React, чтобы что-нибудь найти. Не нужно быть React-разработчиком, чтобы понять суть. Итак, вот код, который я хотел бы особенно выделить:
Обратите внимание на сам код, о котором речь:
Не так сложно понять, что он делает. Если значение maybeKey не неопределено, мы присваиваем переменной key переведённое в строку значение maybeKey. Пометка: это небольшой JavaScript-трюк — » + maybeKey переведёт содержимое maybeKey в строку.
Но здесь вся речь о том, зачем. Комментарий к этому коду отличный. Он указывает на проблему, приводит два примера, а также объясняет, как эту проблему решать в далёкой перспективе и что мы сейчас делаем в краткосрочной.
Если хотите посмотреть на какой-нибудь комментарий, который я оставлял в написанном мной коде, то вот один из них (TypeScript/Closure Compiler). Это хороший пример того типа комментариев, которые я считаю очень ценными.
Любой код в итоге можно понять. В конце концов, код — не что иное, как инструкции, объясняющие компьютеру порядок действий. Код может сбивать с толку, но он не может лгать; если времени достаточно, любой разработчик может пошагово разобрать код и понять, что тот делает. Куда уж сложнее иногда понять, зачем он это делает. Так что оставьте своим коллегам (или будущему-себе-через-шесть-месяцев) немного контекста о том, почему и для чего ваш код делает то, что он делает. Будет гораздо лучше.
Зачем комментировать исходный код и как это делать правильно
Как не забыть о том, что вы имели ввиду полгода назад, когда писали этот программный код? Разбираемся с использованием комментариев.
Комментарии — поясняющие строки в программном коде, которые позволяют понять смысл написанного. Они пишутся для людей, но игнорируются компиляторами и интерпретаторами.
Знакомый, наверно, каждому пример со словами на русском или английском языке после двух слешей — так обычно выглядят комментарии:
Программист, консультант, специалист по документированию. Легко и доступно рассказывает о сложных вещах в программировании и дизайне.
Чем комментарии могут помочь программисту
Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:
Как комментарии оформляют в коде
Комментарии бывают совсем короткими, длиной не более строки, и большими, многострочными.
Однострочные выделяют одиночным символом в начале и продолжают до конца строки, а многострочные могут иметь любую длину, но поддерживаются не всеми языками. Их отмечают специальными символами в начале и конце текста, например, /* и */.
Для выделения комментариев в коде используют разные символы:
Правила, которых принято придерживаться
У разработчиков принято использовать при комментировании несколько простых правил. Так легче работать — больше пользы и не нужно плодить лишние строки кода.
1. Комментарии помещаются прямо над кодом, к которому они относятся. Так проще понять, о чём речь, не вникая в содержание каждой строчки. Совсем короткие пояснения можно писать справа.
2. Комментируют все основные элементы кода: модули, функции, константы, глобальные переменные, интерфейсы, классы и их составные элементы (методы, свойства, константы).
3. Пишут коротко и по делу. Комментарии без смысловой нагрузки страшно раздражают. Не нужно писать комментарии типа «это гениальный код», «таблица1», «! №; %:? *» и подобные.
4. Нельзя, чтобы комментарии оскорбляли кого-то или содержали слова, которые не поймёт технарь. В поддержку движения Black Lives Matter Twitter в своем коде решил не использовать слова slave, master и blacklist. Кто-то из россиян, возможно, улыбнётся, но стандарт есть стандарт.
Документирующие и поясняющие комментарии
В зависимости от того, для чего нужны комментарии, их условно делят на два вида:
Пример на языке Java:
Из такого комментария сразу ясно, что делает программа. Не нужно вникать в исходный текст и изучать техническую документацию. Это особенно важно, если вы работаете в команде и хотите сэкономить время коллег.
Комментарии-описания иногда мешают разработчикам и отвлекают внимание от основного кода. Поэтому в большинстве современных редакторов есть возможность свернуть или скрыть комментарии.
Как комментируют функции и библиотеки
В комментариях к файлам и библиотекам указывают информацию о проекте, назначении модуля, заносят в них имя разработчика, номер версии продукта и лицензию на программное обеспечение.
Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:
Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:
Пример из той же библиотеки Lodash:
Главное здесь — избегать бессмысленных комментариев. Вот пример плохого описания процедуры на языке 1С:
К прикладным процедурам, функциям и классам делайте информативные и понятные заголовки с описанием всех входных и выходных параметров.
Как автоматизировать создание комментариев
В различных IDE есть возможность автоматизировать создание комментариев. Это делается с использованием тегов — дескрипторов, которые начинаются с символа @. Вот самые популярные:
Из таких комментариев автоматически формируется документация программы. Для этого используют генераторы документации, например, javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++, Epydoc для Pithon и другие.
Принцип работы прост. Генератор обрабатывает файл с исходным текстом, находит там имена классов, их членов, свойств, методов, процедур и функций, а затем связывает их с данными из наших комментариев с тегами. Из этой информации формируется документация в формате HTML, PDF, RTF или других.
При разработке библиотек и фреймворков обычно создается документация для API. Со временем она устаревает — в неё не успевают или просто забывают вносить изменения.
Если данные об изменениях в коде отражены в комментариях, с помощью генераторов документацию можно регулярно обновлять.
Когда нужны пояснения в коде, а когда — нет
Бывает, что одних документирующих комментариев недостаточно и нужно добавить пояснения внутри процедур или функций. Такие комментарии облегчают понимание кода — рассказывают, почему автор программы сделал что-то так, а не иначе.
Но иногда эти пояснения только ухудшают наглядность кода, бывают бессмысленны и даже вредны. Например, совершенно не нужны комментарии, просто пересказывающие действия программы:
Если вы вставили промежуточные комментарии для отладки или объяснения результатов, после окончания работы их нужно убрать. Иначе они будут захламлять код.
Например, функция вычисляет окончательную сумму, прибавляя проценты к основной. Для проверки программист вывел на экран промежуточный результат, а после закомментировал ненужный фрагмент.
После отладки их лучше удалить, оставив строки:
Простой код, без многочисленных циклов, ветвлений и переходов, пишут и структурируют так, чтобы никаких дополнительных пояснений к нему не требовалось.
Но бывают исключения. Допустим, разработчик попробовал несколько вариантов решения и выбрал один, не самый очевидный. Потом забыл ход своих мыслей, открыл код и решил использовать «более правильный и оптимальный вариант». И тут он понимает, что новое решение хуже старого; более того, раньше он уже это пробовал делать. Приходится откатывать всё назад. Чтобы не попасть в такую ситуацию, пишите поясняющие комментарии.
Пример на языке JavaScript:
Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).
Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:
Это неудачный комментарий: непонятно, зачем количество умножать на 2.
Правильно будет так:
В любом случае, старайтесь писать поясняющие комментарии как можно реже.
Комментарии в сложном коде и рефакторинг
В сложной и запутанной программе не обойтись без поясняющих комментариев. Но иногда лучше упростить сам код: разбить на отдельные функции, уменьшить размеры элементов, упростить циклы и так далее. А самим функциям, константам и переменным дать «говорящие» имена, объясняющие их назначение.
Например, есть метод, который сравнивает числа a и b. Если a > b, он возвращает true, a если a
Весь этот громоздкий кусок кода можно значительно упростить, просто убрав блок if-else:
Теперь метод выглядит намного проще и элегантнее, хотя его суть не изменилась. Подобные преобразования называются рефакторингом.
Рефакторинг меняет структуру кода, оставляя неизменной его суть. Он повышает читаемость кода и облегчает процесс его доработки. Рефакторинг не заменяет комментирование, но с ним комментариев нужно намного меньше.
Что в итоге
Комментарии — отличная штука. Они помогают команде разработчиков работать над общим проектом. А если программист один, позволят ему даже через много лет вспомнить ход своих мыслей. Но комментариев должно быть мало, иначе они превратятся во флуд.
Комментировать нужно основные элементы кода, неочевидные решения, сложные бизнес-процессы, тонкости решений и тому подобное. Не пишите комментарии, объясняющие, что и как делает процедура или функция, — это бессмысленно.
И помните, что комментарий — не панацея, он не спасёт плохой код, даже если сделает его понятнее. Сложные и запутанные фрагменты сокращайте и делайте рефакторинг, а комментируйте по минимуму.
Научиться использовать комментарии, верно документировать исходный код, писать его понятным для коллег и читабельным даже через много лет вы можете на наших курсах по программированию. Выбирайте любой и становитесь профессионалом.
Лучшие практики написания комментариев к коду
Известный профессор МТИ Гарольд Абельсон сказал: «Программы нужно писать для того, чтобы их читали люди, и лишь случайно — чтобы их исполняли машины». Хотя он намеренно преуменьшил важность исполнения кода, однако подчёркивает, что у программ две важные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и с одинаковой лёгкостью воспринимают все синтаксически корректные программы. У людей всё иначе. Одни программы нам воспринимать легче, чем другие, и мы ищем комментарии, которые помогут нам разобраться.
Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.
Как писал Питер Фогель:
Первое правило: комментарии не должны дублировать код
Многие начинающие программисты пишут слишком много комментариев, потому что их к этому приучили. Я видел, как старшекурсники на факультете информатики добавляют комментарии к каждой закрывающей скобке, чтобы показать закрытие блока:
Я слышал о преподавателях, которые требуют от студентов комментировать каждую строку кода. Для совсем новичков это может быть оправдано, однако такие комментарии как боковые колёсики на детском велосипеде, которые по мере роста надо снять.
Неинформативные комментарии вредны, потому что:
Комментарий не добавляет полезной информации и требует усилий по поддержке.
Требования комментировать каждую строку справедливо высмеяли на Reddit:
Второе правило: хорошие комментарии не оправдывают непонятный код
Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:
Комментарий был бы не нужен, если дать переменной правильное название:
Как написали Керниган и Плогер в книге «The Elements of Programming Style»: «Не комментируйте плохой код, а переписывайте его».
Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде
Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:
Отладка вдвое труднее первоначального написания кода. Поэтому если вы пишете код как можно умнее, то вы по определению не настолько умны, чтобы его отладить.
Предупреждение читателям, чтобы они держались подальше от вашего кода, сродни включению аварийных огней: признание в том, что вы делаете что-то незаконное. Лучше перепишите код так, чтобы вы сами понимали его достаточно, чтобы объяснить другим. Или ещё лучше, чтобы его вообще не требовалось объяснять.
Четвёртое правило: комментарии должны исключать путаницу, а не вносить её
Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:
[Питер Самсон] особенно усложнял ситуацию тем, что отказывался добавлять в свой исходный код комментарии с пояснением, что он делает в каждом конкретном случае. Одна из распространённых программ, написанных Самсоном, состояла из сотен инструкций на ассемблере с единственным комментарием после инструкции под номером 1750. Комментарий был такой: RIPJSB, и люди ломали головы над тем, что это означает, пока кто-то не догадался, что в 1750-м году умер Бах, и что Самсон написал аббревиатуру фразы “Rest In Peace Johann Sebastian Bach”.
Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.
Пятое правило: объясняйте в комментариях не идиоматический код
Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):
Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:
Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.
Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.
Если вы такой же, как и большинство программистов, то иногда вы используете найденный в сети код. Добавляйте ссылку на исходник, чтобы будущие читатели имели полный контекст, например:
Если перейти по ссылке, то вы обнаружите, что:
Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.
Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.
Вы также можете ссылаться на оказавшиеся полезными руководства в качестве благодарности их авторам и ради экономии времени читателей:
Седьмое правило: добавляйте ссылки на внешние примеры в тех случаях, когда это полезнее всего
Конечно, не все ссылки ведут на Stack Overflow.
Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.
Восьмое правило: исправляя баги, добавляйте комментарии
Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:
Комментарий не только помогает понять код в конкретных методах, но и определить, нужен ли ещё этот код и как его тестировать. Также комментарий может ссылаться на систему отслеживания ошибок:
Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).
Девятое правило: помечайте комментариями незаконченные реализации
Иногда необходимо проверять код, даже несмотря на его ограничения. Хотя может быть заманчиво не рассказывать о недостатках своего кода, лучше сделать это явно, например, в комментарии TODO:
Стандартный формат для таких комментариев помогает оценить и адресовать технический долг. Ещё лучше, если добавите задачу в систему отслеживания ошибок и вставите ссылку в комментарий.
Комментирование кода: хорошие, плохие и отвратительные комментарии
Комментирование кода: хорошие, плохие и отвратительные комментарии
«Хороший код — это самодокументируемый код». Вы слышали эту фразу раньше? Я тоже. Более чем за 20 лет написания кода я слышал эту фразу чаще других. Это уже клише.
У этой фразы, как и у многих других клише, есть доля правды. Но смысл этого предложения давно потерялся, многие люди уже не понимают, что значит это выражение из-за постоянного и повсеместного использования.
В этой статье мы рассмотрим хорошие, плохие и отвратительные примеры комментирования в коде.
Начинающие разработчики должны помнить, что существует два типа комментариев в коде: поясняющие и документационные.
Документационные комментарии
Документационные комментарии предназначены для всех, кто когда-либо будет использовать ваш исходный код, но вряд ли сможет понять или прочитать его правильно. Если вы создаёте библиотеку или фреймворк, которые будут использоваться другими разработчиками, то вам нужно будет разработать документацию для API.
Чем больше API-документация отдалена от вашего кода, тем больше вероятность того, что она станет неточной или устаревшей с течением времени. Хорошим способом преодоления этой проблемы является документирование в самом коде. Таким образом вы сможете извлечь документацию с помощью специальных инструментов.
Посмотрите на пример кода из Lodash — популярной библиотеки для JavaScript:
Недостатком этих комментариев можно назвать лишний шум в коде, который они создают. Этот шум создаёт сложности при чтении кода другими разработчиками, участвующих в его разработке и поддержании.
Однако в большинстве современных редакторов есть возможность скрыть комментарии, чтобы лучше сосредоточиться на редактировании кода.
Поясняющие комментарии
Поясняющие комментарии предназначаются для всех (включая вас в будущем), кто будет заниматься поддержкой, рефакторингом и расширением вашего кода.
Зачастую уточняющий комментарий к вашему коду является его отражением. По пояснению можно судить нагружен ваш код или нет. Следует пытаться удалять пояснения в коде, упрощая его, ведь «хороший код — самодокументированный код».
Приведу пример плохого, но забавного пояснения:
Вместо того, чтобы писать амфибрахий для украшения запутанного кода, автор мог бы с пользой потратить время и поработать над функцией, облегчив чтение и понимание кода.
Поймите меня правильно, бывают моменты, когда небольшая порция юмора помогает расслабиться, особенно когда вы просто утопаете в работе. Но не пишите забавный комментарий, чтобы приукрасить плохой код. Именно из-за таких шуток в будущем мало кто захочет исправлять код и заниматься его рефакторингом.
Вам действительно хочется приукрасить рифмой свой плохой код, чтобы кодеры ухмыльнулись и проигнорировали его, двигаясь дальше?
Также бывают случаи, когда авторы добавляют излишние пояснения. Например, если код очень прост и понятен любому, то нет необходимости добавлять пояснения.
Не совершайте подобные глупости:
Тем не менее, бывают случаи, когда поясняющие комментарии нужны, вне зависимости от того, как выглядит ваш код.
Обычно это происходит, когда вам нужно добавить контекст к неинтуитивному решению.
Вот хороший пример из фреймворка Lodash:
Иногда бывают случаи, когда оказывается, что на первый взгляд наивное решение проблемы является наилучшим после долгих экспериментов и размышлений. В подобных моментах почти неизбежна ситуация, когда другой разработчик, подумав, что он умнее, чем вы, начнёт копаться в коде, но в итоге выяснит, что ваше решение всё это время оставалось лучшим.
А иногда тем самым «более умным» кодером можете оказаться вы сами. Поэтому в таких случаях лучше оставлять комментарии к коду, чтобы в будущем сэкономить своё и чужое время и нервы.
Комментарий снизу полностью отражает суть мысли выше:
Опять же, комментарий сверху содержит больше юмора, чем пользы. Вам СЛЕДУЕТ оставлять комментарии, предупреждающие других от поиска какого-либо «лучшего решения», если вы сами уже пытались это сделать, но ничего хорошего из этого не вышло. В комментарии следует указать, какое решение вы пытались найти и почему вы решили, что оно не подходит в данной ситуации или не работает.
Отвратительные комментарии
Мы уже узнали, что такое хорошие и плохие комментарии к коду. Теперь пришло время ознакомиться с отвратительными комментариями.
К сожалению, в любой работе бывают моменты разочарования. Такое может случиться и во время написания кода, когда у вас возникнет соблазн выразить всё своё разочарование в комментариях.
При работе с большими объёмами кода вы можете столкнуться с различными негативными комментариями, начиная от циничных и депрессивных до резко негативных и злых.
Подобные моменты могут показаться забавными или, возможно, помогут вам разрядиться немного во время описания своего жизненного разочарования в комментарии. Но следует помнить, что иногда ваш код может дойти до продакшена. В таком случае вы не будете выглядеть умным или компетентным в своей сфере.
Уважайте себя и других разработчиков и не допускайте подобных комментариев в своём коде.