Коментировать или комментировать как правильно пишется

Лучшие практики написания комментариев к коду

Известный профессор МТИ Гарольд Абельсон сказал: «Программы нужно писать для того, чтобы их читали люди, и лишь случайно — чтобы их исполняли машины». Хотя он намеренно преуменьшил важность исполнения кода, однако подчёркивает, что у программ две важные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и с одинаковой лёгкостью воспринимают все синтаксически корректные программы. У людей всё иначе. Одни программы нам воспринимать легче, чем другие, и мы ищем комментарии, которые помогут нам разобраться.

Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.

Как писал Питер Фогель:

1. Написание и поддержка комментариев требует усилий.
2. Ваш компилятор не смотрит на комментарии, поэтому невозможно определить их корректность.
3. С другой стороны, вы гарантируете, что компьютер делает именно то, что предписывает ваш код.

Первое правило: комментарии не должны дублировать код

Многие начинающие программисты пишут слишком много комментариев, потому что их к этому приучили. Я видел, как старшекурсники на факультете информатики добавляют комментарии к каждой закрывающей скобке, чтобы показать закрытие блока:

Я слышал о преподавателях, которые требуют от студентов комментировать каждую строку кода. Для совсем новичков это может быть оправдано, однако такие комментарии как боковые колёсики на детском велосипеде, которые по мере роста надо снять.

Неинформативные комментарии вредны, потому что:

• вносят визуальный беспорядок;
• отнимают время на написание и чтение;
• могут устареть.

Комментарий не добавляет полезной информации и требует усилий по поддержке.

Требования комментировать каждую строку справедливо высмеяли на Reddit:

Второе правило: хорошие комментарии не оправдывают непонятный код

Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:

Комментарий был бы не нужен, если дать переменной правильное название:

Как написали Керниган и Плогер в книге «The Elements of Programming Style»: «Не комментируйте плохой код, а переписывайте его».

Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде

Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:

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

Четвёртое правило: комментарии должны исключать путаницу, а не вносить её

Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:

Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.

Пятое правило: объясняйте в комментариях не идиоматический код

Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):

Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:

Я удивился, почему бы не заменить его просто на if (b) , как сделал бы это на Java. В результате небольшого исследования я выяснил, что допускающие пустое значение булевы переменные явным образом сравниваются с true, чтобы избежать уродливой проверки на null:

Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.

Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.

Если вы такой же, как и большинство программистов, то иногда вы используете найденный в сети код. Добавляйте ссылку на исходник, чтобы будущие читатели имели полный контекст, например:

• какую задачу вы решали;
• кто предоставил код;
• почему это решение рекомендовано;
• что думали об этом комментаторы;
• работает ли это ещё;
• как его можно улучшить.

Если перейти по ссылке, то вы обнаружите, что:

• Автора кода зовут Tomáš Procházka, он входит в топ-3% на Stack Overflow.
• Один из комментаторов предложил улучшение, уже внесённое в репозиторий.
• Другой комментатор предложил способ избежать пограничного случая.

Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.

Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.

Вы также можете ссылаться на оказавшиеся полезными руководства в качестве благодарности их авторам и ради экономии времени читателей:

Седьмое правило: добавляйте ссылки на внешние примеры в тех случаях, когда это полезнее всего

Конечно, не все ссылки ведут на Stack Overflow.

Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.

Восьмое правило: исправляя баги, добавляйте комментарии

Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:

Комментарий не только помогает понять код в конкретных методах, но и определить, нужен ли ещё этот код и как его тестировать. Также комментарий может ссылаться на систему отслеживания ошибок:

Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).

Девятое правило: помечайте комментариями незаконченные реализации

Иногда необходимо проверять код, даже несмотря на его ограничения. Хотя может быть заманчиво не рассказывать о недостатках своего кода, лучше сделать это явно, например, в комментарии TODO:

Стандартный формат для таких комментариев помогает оценить и адресовать технический долг. Ещё лучше, если добавите задачу в систему отслеживания ошибок и вставите ссылку в комментарий.

Как пишется слово: «комментарий» или «коментарий»

Данное слово является существительным, а употребляется в значении «какое-либо пояснение к тексту». Со значением слова всё стало понятно. А возникнут ли вопросы при написании слова? Я думаю, что да. Поэтому, давайте разберёмся.

Как же правильно пишется: «комментарий» или «коментарий»?

Согласно орфографической норме русского языка изучаемое слово пишется, как в первом варианте:

Почему же мы напишем две согласных буквы «м»?

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

Но в нашем случае это сделать невозможно, так как наше существительное является словарным словом, а его правописание необходимо запомнить!

А правильность написания слова Вы можете проверить по орфографическому словарю русского языка.

Склонение слова «комментарий»

Склонение слова «комментарий» — это его изменение по падежам и числам. Узнаем, какая форма родительного падежа «жду комментарий» или «жду комментариев» является правильной согласно морфологической норме русского литературного языка.

Сначала выясним, какой тип склонения имеет слово «комментарий» в русском языке. Прежде чем изменять по падежам слово «комментарий», определим, что это существительное мужского рода. Оно сочетается с местоимениями и прилагательными:

• он, мой комментарий ;
• злободневный комментарий

По этим грамматическим признакам можно понять, что это слово принадлежит ко второму склонению.

Как правильно «жду комментарий» или «жду комментариев»?

В склонении существительного «комментарий» представляет интерес форма родительного падежа множественного числа. С того времени как интернет прочно вошел в нашу жизнь, многие пользователи хотят узнать, как правильно писать

«жду комментарий» или «жду комментариев», «узнали из комментарий» или «узнали из комментариев»?

Это заимствованное слово восходит к латинскому глаголу commentare («объяснять», «толковать»), а далее образовано существительное commentarium , что обозначает

• разъяснительное примечание к тексту;
• сопроводительное, критическое замечание по поводу чего-либо.

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

Чтобы убедиться в этом, просклоняем анализируемое существительное:

• и. п. (что?) комментарий , комментари и
• р. п. узнаю (из чего?) из комментари я , из комментари ев
• д. п. рад (чему?) комментари ю , комментари ям
• в. п. читаю (что?) комментарий , комментари и
• т. п. интересуемся (чем?) комментари ем , комментари ями
• п. п. расскажу (о чем?) о комментари и , о комментари ях .

Итак, в русском литературном языке согласно морфологической норме отвлеченное существительное «комментарий» в родительном падеже множественного числа имеет единственно правильную грамматическую форму с окончанием -ев:

• жду комментари ев
• нет комментари ев
• узнать из комментари ев
• оставить без комментари ев
• получить многокомментари ев .

Чтобы усвоить это написание, прочтём примеры предложений.

Примеры

Я жду ваших комментариев по поводу этого утверждения.

Посмотрите, сколько комментариев написано об этой статье!

Этот несерьёзный ответ не заслуживает столько комментариев.

Узнаем, как обойтись без лишних комментариев.

Тебе хочется пройти мимо этих пустых комментариев?

Как жаль, что в прессе так мало комментариев об этом важном событии.