Как написать комментарий в: Пишем комментарии правильно » Журнал практической электроники Датагор

Содержание

что это такое и как их писать

Комментарии в интернете нужны для быстрого обмена мнениями между читателями. Это-то что-то вроде отзывов. Прочитали статью или посмотрели видеоролик – высказались.

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

Такая функция есть на большинстве информационных сайтов и блогов. Также она имеется в социальных сетях – Одноклассниках, Вконтакте, Facebook, Youtube и других.

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

Можно, конечно, поискать адрес электронной почты автора и написать ему письмо. Не исключено даже, что он его прочитает и как-то отреагирует. Но это сложный способ, да и не каждый публикует свои контактные данные. Гораздо проще написать комментарий, в котором поделиться тем, что знаешь и умеешь. Скорее всего, автор прочитает это сообщение и ответит на него. И другие читатели статьи тоже увидят эту информацию и смогут высказаться.

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

Вот как раз комментарии для этого и предназначены. В них люди высказываются по поводу полученной информации и делятся своим опытом.

Где найти комментарии

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

Выглядят они примерно так:

В Одноклассниках они находятся под каждой новостью, заметкой или фотографией:

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

А в социальной сети Вконтакте они размещаются сразу под заметкой:

Конечно, внешний вид комментариев отличается на разных сайтах. Но отображение у них, как правило, одинаковое: каждое сообщение – это отдельный кусочек текста с указанием имени и даты публикации.

Сообщения добавляются по мере их поступления и сортируются по дате/времени.

Бывает, что комментариев к какому-то материалу становится очень много и часть их переносится на другие станицы:

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

Как добавить комментарий

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

Оставить сообщение к заметке в социальных сетях очень просто – печатаем текст в специальное поле и отправляем.

На сайтах и блогах немного сложнее, но тоже ничего особенного.

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

Обычно нужно указать свое имя (можно вымышленное) и адрес электронной почты. Ну, и, конечно, текст сообщения.

Адрес электронной почты увидит только автор материала – на странице он опубликован не будет.

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

И еще одна важная деталь – защита от спама. Эта часть обязательна к заполнению – без нее сообщение не отправится. На разных сайтах она выглядит по-разному. Иногда нужно напечатать такие вот закрученные буквы и цифры.

Но есть и другие варианты. Например, поставить птичку рядом с надписью «Это не спам»:

Или напечатать в поле сумму двух цифр:

Если какое-то из обязательных полей заполнено неправильно, то сразу после отправки появится сообщения об ошибке. Значит, нужно перепечатать «проблемную» часть, и попробовать снова добавить комментарий.

Необязательные поля

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

Например, поле «Сайт».

Его заполнять необязательно – это для тех, кто хочет показать автору и читателям адрес своего (личного) сайта.

Или подписка на новые комментарии.

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

Как получить ответ на свой комментарий

Ответ придет туда же, где Вы опубликовали свое сообщение. То есть искать его нужно именно на той самой странице.

В социальных сетях это сделать проще. В Одноклассниках, например, есть специальная часть Обсуждения.

А вот на сайтах и блогах дело обстоит хуже. На многих из них комментарии сразу не публикуются.

Как правило, в таких случаях после отправки появляется примерно такое уведомление:

Значит, на этом сайте все оставленные сообщения проверяет администратор или автор (владелец) ресурса. Он читает их и какие-то размещает, а какие-то удаляет.

Так что Ваше сообщение может быть вообще не опубликовано. Например, администратор счел его оскорбительным или бессмысленным.

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

Никто не будет на Вашу почту присылать ответ на заданный вопрос. Его нужно искать там, где он был задан.

Автор: Илья Кривошеев

Как пользователю написать комментарий на сайте: основные моменты | Интернет

Написать комментарий на сайте – это значит выразить свое мнение по материалу, изложенному на сайте, и отправить его на всеобщее обозрение.

Опубликованный комментарий может прочитать любой человек, который попадет на сайт – взрослый, подросток, ребенок. Таким образом, комментарии пишутся не только для автора (авторов) статьи (блога, видео, аудио и пр.), но и абсолютно для всех пользователей интернета, которые будут читать или просматривать (прослушивать) опубликованный материал.

Содержание:
1. Некоторые правила написания текста комментария
2. В чем главное отличие комментария от электронного письма

3. Где можно оставлять комментарии
4. Как заполнить поля при написании комментария на сайте

5. Что значит «ваш комментарий отправлен на модерацию»
6. Почему иногда нельзя написать комментарий на сайте

7. Соцсети как альтернатива комментариям на сайте
8. Как скопировать текст из Word и вставить его в комментарий
9. О комментариях за деньги

Как написано в Википедии, комментарий (от латинского commentarius — заметки, записки; толкование) — пояснения к тексту, рассуждения, замечания о чем-нибудь или замечания, вопросы по поводу чего-либо в Интернете — к посту (сообщению).

Слово «комментарий» иногда сокращают – «коммент» с ударением на первый слог (кОммент) или «комент» с ударением на второй слог (комЕнт), так слово становится по произношению похожим на английское слово «comment», означающее то же самое. А слово «комментировать» сокращается до «комментить» или «коментить» – благодаря особенностям и возможностям грамматики русского языка. К молодежному сленгу относятся слова «камент», «каментить».

Правильно писать в текстах «комментарий» и «комментировать». Впрочем, допустимы сокращения «коммент», «комментить».

Варианты с «комент», «камент» и «коментить», «каментить» – это уже другой мир, мир сленга, со своим языком и правилами общения. Думаю, что употребление подобного сленга не отменяет необходимости хорошего знания русского языка. А последнее всегда радует.

Некоторые правила написания текста комментария

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

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

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

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

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

Нет особого смысла «спамить» – это когда автор комментария пытается в комментариях к статье дать какую-то рекламу своего товара, услуг или навязчиво предложить некую свою тему, которую автор комментария считает намного важнее всего остального.

Обычно комментарии в той или иной степени проходят проверку, модерацию со стороны администрации сайта (об этом написано ниже), и не будут пропущены, не будут опубликованы. Какой смысл тратить время на получение отрицательного результата? Конечно, спам-комментарии чаще рассылают автоматически, без участия человека, это делает программа-робот. Но вопросы автоматических рассылок комментариев мы здесь рассматривать не будем, это отдельная тема.

В чем главное отличие комментария от электронного письма

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

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

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

Получается, что у комментариев широта охвата аудитории несравнимо больше, чем у электронного письма. В Интернете количество людей которые могут прочитать комментарий практически не ограничено ничем, кроме времени (чем дольше хранится комментарий, тем больше людей его могут прочитать) и посещаемости того ресурса, где оставлен комментарий (в Интернете есть ресурсы с количеством посещений свыше миллиона человек в сутки).

Где можно оставлять комментарии

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

Чтобы понять, есть ли возможность написать комментарий на сайте, надо открыть любую публикацию. Затем пролистать ее до конца и посмотреть, есть ли там форма для комментирования. Например, форма для комментариев может выглядеть так, как показано на рис. 1:

Рис. 1. Форма для комментирования на сайте

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

Цифра 1 на рис. 1 – поле для ввода комментария. Желательно выражать свое мнение строго по материалам опубликованной статьи и в сдержанной форме, даже если статья или ее автор чем-то не нравится читателю, даже если представленные материалы расходятся с мнением автора комментария.

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

2 на рис. 1 – поле для ввода своего имени. Обычно можно указать свое имя или любое другое, например, ник автора комментария (некое звучное, придуманное имя), выдуманный псевдоним и прочее. На некоторых сайтах поле для ввода имени отсутствует.

3 на рис. 1 – поле для того, чтобы ввести адрес электронной почты. Если Вы заинтересованы в получении ответа на свой комментарий, то следует указать свой реальный e-mail, причем без ошибок.

Если же Вам не нужен ответ на ваше сообщение, тогда можно указать произвольный, несуществующий адрес электронной почты, например, [email protected]. Совсем не указывать адрес электронной почты нельзя, иначе комментарий не будет размещен на сайте.

При написании даже несуществующего адреса электронной почты нужно соблюдать правила именования адресов. Например, в адресе [email protected] есть имя (321), обязательный значок «@», снова имя (mail), точка «.», и сокращение «ru» или «com», «net» и т.п.

Цифра 4 на рис. 1 – если кликнуть по маленькому черному треугольничку, то появится меню с выбором (рис. 2):

Рис. 2. Выбор варианта получения ответов на комментарий

По умолчанию, если ничего не менять, будет использован вариант: «Ответы на мои комментарии» (рис. 2). В этом случае важно указать корректный e-mail для получения ответа.

Однако можно выбрать вариант «Не подписываться» (рис. 2). Тогда Вы НЕ получите ответ на свое сообщение (если он будет). Выбор варианта «Все» означает, что Вы получите все комментарии от всех читателей, оставленные к этой статье.

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

Цифра 5 на рис. 1 – проверяем (глазами) заполненные поля, вносим исправления, если обнаружены ошибки или неточности, и жмем на кнопку «Отправить комментарий». На разных сайтах название кнопки может быть иным. Тем не менее, эта кнопка везде имеет одинаковую функцию – отправляет ваш комментарий на сайт.

На некоторых сайтах перед отправкой комментария необходимо ввести капчу для предотвращения спама, который распространяют боты – автоматические программы.

Слово капча происходит от сокращения CAPTCHA — англ. Completely Automated Public Turing test to tell Computers and Humans Apart. В переводе это «полностью автоматизированный публичный тест Тьюринга для различения компьютеров и людей» — компьютерный тест, используемый для того, чтобы определить, кем является пользователь системы: человеком или компьютером.

Автоматические программы не в состоянии правильно ввести предлагаемые значения капчи, для этого программы должны были бы обладать интеллектом, сравнимым с интеллектом человека. К счастью, такого пока нет, иначе роботы нас бы точно победили в интернет пространстве…

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

Поэтому, чтобы не потерять текст комментария в случае неудачи в момент его отправки, если у Вас длинный, большой важный комментарий, то рекомендуется предварительно его написать в текстовом редакторе, например, в Блокноте или в Word. Тогда у Вас под рукой будет копия комментария, и его можно будет отправить на сайт повторно, правильно введя капчу.

После того, как нажата кнопка для отправки, комментарий будет либо

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

Что значит «ваш комментарий отправлен на модерацию»

Допустим, что Вы заполнили на сайте все поля (рис. 1) и написали комментарий, нажали на кнопку «Отправить» (название кнопки может быть другим). А в ответ выскакивает сообщение, что Ваш комментарий отправлен на модерацию. При этом Вы видите, что комментарий куда-то исчез, как будто его и не было.

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

В результате модерации Ваш комментарий может быть опубликован, либо удален без объяснения причин. Опубликованный комментарий Вы сможете увидеть на сайте спустя какое-то время. Если же комментарий будет удален, то на сайте он так и не появится, и никаких уведомлений Вы не получите.

Казалось бы – несправедливо, вот так без уведомления удалять, не публиковать комментарии. Однако почти на каждом сайте есть своя Политика – свод правил, в том числе правила комментирования. Если пользователь нарушил правила, то его комментарий не допускается к публикации.

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

Почему иногда нельзя написать комментарий на сайте

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

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

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

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

Например, на сайте Лента.ру можно увидеть сообщение: «Комментарии к материалу закрыты в связи с истечением срока его актуальности». В правилах этого портала есть пояснение: «Для защиты от спама и попыток распространения запрещенных законодательством РФ материалов комментарии ко всем новостным заметкам автоматически отключаются спустя сутки после публикации заметки».

Соцсети — альтернатива комментариям на сайте?

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

Что касается упомянутого выше портала Лента ру, где закрыта возможность комментировать материалы, то у него есть своя страница ВКонтакте, где можно довольно свободно писать комментарии. Конечно, комментарии в социальных сетях тоже проверяются модераторами, так что не следует думать, что в соцсетях можно абсолютно все.

Чтобы появилась возможность выражать свое мнение в социальной сети и оставлять там сообщения, требуется регистрация пользователя в той или иной сети. Другими словами, нужно быть зарегистрированным пользователем в социальной сети, ибо там нельзя писать комментарии как анонимный пользователь.

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

В целях борьбы с анонимностью есть сайты, которые НЕ являются соцсетями, но там можно оставить комментарий только, если пользователь авторизован в какой-либо соцсети. Например, надо быть авторизованным пользователем ВКонтакте или на Фейсбуке. Только тогда появляется возможность отправить свой комментарий на такой сайт.

На некоторых сайтах автоматически публикуются сообщения пользователей из соцсетей. Что это означает? В соцсети публикуется анонс материала (статьи, поста), опубликованного на сайте. Анонс может публиковаться в группе, либо на личной страничке автора статьи. Пользователи пишут к этому материалу комментарии, которые из соцсети автоматически дублируются на сайте автора статьи. Поэтому пользователь ошибается, если думает, что, например, сообщения в Одноклассниках, написанные к статье какого-либо автора, дальше этой соцсети никуда «не уйдут».

Как скопировать текст из Word и вставить его в комментарий

Казалось бы, зачем нужен текстовый редактор Microsoft Word для написания комментария. Однако бывают различные сбои

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

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

Как скопировать текст сообщения в текстовом редакторе, например, в Word?

Сначала текст надо выделить (другими словами, засинить).
Затем нажать на две клавиши одновременно Ctrl+C (клавиша с английской буквой «C»).
Открыть поле для ввода комментария на сайте, обязательно поставить курсор мыши в это поле.
Нажать две клавиши одновременно Ctrl+V (буква «V» английская).

Такая процедура называется копипастом, что в переводе с английского copy-paste означает «скопировал – вставил». После произведенных выше четырех действий комментарий будет вставлен в поле. Остается разве что заполнить остальные поля при их наличии и отправить комментарий на сайт.

О комментариях за деньги

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

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

Кроме того, есть биржи контента с аналогичной работой для желающих написать комментарии за деньги.

Более подробно возможные варианты работы по комментированию за деньги приведены здесь:
Заработок на комментариях в Интернете

Дополнительные материалы:

1. Неписаные правила СМС-общения

2. Десять правил этикета электронной почты

3. Что такое посткроссинг

4. Что такое контент сайта и с чем его едят

Руководство инженера по написанию осмысленного кода Комментарии

«Что это делает?»

«Почему это не билет?»

Были там? Если вы чем-то похожи на большинство инженеров, можно с уверенностью сказать, что это случается с вами много раз .

Наиболее очевидное и непосредственное преимущество написания хороших комментариев заключается в том, что они облегчают понимание кода другими.

Но когда мы отрабатываем лучшие практики комментирования кода (в том числе когда и , когда , а не для написания комментариев), мы можем открыть еще более важные и долгосрочные преимущества, такие как:

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

‍

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

В этом полном руководстве по написанию осмысленных комментариев к коду мы:

Объясним, какие существуют типы комментариев
Обсудим, когда и как писать комментарии к коду
Расскажем о некоторых передовых методах комментирования кода
Обсудим, когда не их писать (а что делать вместо этого!)

Стоит ли вообще использовать комментарии?

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

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

Типы комментариев (и когда их использовать)

1. Контекстные комментарии

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

Первый тип — это комментарии на уровне модуля. Они описывают назначение классов, функций и методов.

Эти комментарии могут включать…

Параметры, которые принимает функция
Результат, который она генерирует
Любые функции модуля, которые нельзя понять с первого взгляда.

Второй тип — логические комментарии. Они объясняют код в контексте, где бы они ни были необходимы.

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

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

✅ Когда их использовать:

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

Например, неясно, являются ли параметры «начало» и «конец» включающими или исключающими. Комментарий избавил бы читателей от разгадки.

Меньшее количество комментариев часто означает более читаемый код. Если кто-то увидит комментарий, он поймет, что он острый и ценный.

❌ Когда их следует избегать:

Когда назначение функции очевидно
В библиотеках или API
Когда это должно быть отмечено как проблема. (Вот как команды погребают под кучей технических долгов, даже не подозревая об этом.)

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

Инженерная практика, которую должна принять ваша команда, заключается в последовательном документировании ненужного сложного кода как задач. Это позволяет избежать накопления серьезного технического долга, который может быть трудно погасить. Если вы еще не используете для этого инструмент, попробуйте Jira или Linear для отслеживания проблем на основе приложений. Или попробуйте Stepsize для отслеживания технического долга и управления им из редактора кода.

2. TODO/FIXME

TODO и FIXME повсюду. Но они сопряжены со значительными затратами.

TODO — отличный инструмент для одиночной игры… Они отлично подходят для временного сброса мыслей, чтобы вы могли сосредоточиться на том, что делаете. TODO определенно лучше, чем список сбоку, потому что у них есть контекст.

… Но ужасный многопользовательский инструмент . Когда TODO попадают в `main`, вы получаете бесконечный, невидимый список невыполненных работ , который не подлежит действию.

Плохая практика комментариев — прямой путь к растущему техническому долгу и снижению качества кода.

Используйте TODO, чтобы помочь вашему личному процессу разработки кода. Никогда не отправляйте TODO в раздел «main».

Если в вашей кодовой базе есть TODO, используйте инструмент управления задачами Stepsize, чтобы преобразовать их в задачи, не выходя из IDE. Инструмент также будет отображать TODO в PR, где вы можете превратить их в задачи.

Три передовых метода написания комментариев к коду

1. Сосредоточьтесь на

почему
Лучшие комментарии к коду — те, которые вам не нужны . Лучшие комментарии нельзя заменить кодом.
Взгляните на этот пример, который мы заимствовали у Джефа Раскина:
/* Бинарный поиск оказался медленнее, чем алгоритм Бойера-Мура для интересующих наборов данных, поэтому мы использовали более сложный, но более быстрый метод, хотя эта проблема на первый взгляд не кажется поддающейся решению с помощью метода строкового поиска. */
Код должен быть написан как можно проще. Лучшие комментарии объясняют неизбежную сложность. Например, мы можем добавить комментарий, объясняющий бизнес-приложение кода или обоснование выбора конкретного алгоритма.
Код говорит вам как . Комментарии говорят вам , почему . ‍
2. Не навязывайте TODO. Создавайте проблемы.
TODO должны быть только для одного игрока. TODO, которые передаются, приводят к бесконечному, невидимому отставанию , который не подлежит действию.
Если вы продвигаете TODO, вместо этого вы должны создавать задачу. Когда оставлять TODO в базе кода является привычкой всей команды, это приводит к растущему техническому долгу.
Используйте такой инструмент, как Stepsize, чтобы управлять проблемами, не выходя из базы кода. Stepsize интегрируется с такими платформами, как Jira и Linear, если вы этого хотите. Расширение VSCode находится здесь, а расширение Jetbrains — здесь. Этот инструмент позволит вам:
Преобразовать TODO в задачи одним щелчком
Отметьте задачи и проблемы в PR
Визуализируйте проблемы и технический долг в различных частях вашей кодовой базы
Сделайте управление проблемами простым для инженеров
Станьте героем технического долга!
Такие инструменты, как Stepsize, могут очищать TODO и управлять проблемами
3. Выберите и задокументируйте соглашения.
Документирование соглашений поможет сохранить согласованность ваших комментариев. Это заставляет команды решать, что будет комментироваться и в каком формате.
Возможно, вы программируете на языке с помощью инструмента компиляции документов, такого как Javadoc для Java, godoc для Go! Или Doxygen для C++. Используйте их — хотя они и не идеальны, структурные преимущества перевешивают недостатки.
Выбирайте инструменты и методы решения проблем, интуитивно понятные для отдельных инженеров и приносящие пользу команде. Вы запрещаете TODO в `main` или у вас есть политика документирования проблем? Убедитесь, что это все понимают.
Как только передовой опыт становится привычкой в команде, он становится легким вкладом в более быструю и качественную разработку кода и надлежащее управление техническим долгом.
Закрепление ваших принципов окупается, когда инженеры присоединяются к вашей команде или покидают ее.
Округление
Комментирование кода — это не только умение писать хорошие комментарии. Это также о том, чтобы знать, когда , а не , и что делать вместо этого.
Когда мы делаем это правильно, мы не просто облегчаем понимание другим. Мы:
Ускорение разработки
Улучшение качества кода
Повышение морального духа команды
Управление и устранение технического долга
20002 Во-первых, когда мы пишем хорошие комментарии, мы постоянно выявляем важную информацию об особенностях кода и архитектурных решениях.
Во-вторых, когда мы избегаем комментариев о проблемах кода и вместо этого создаем проблемы, мы обеспечиваем возможность действий и видимость проблем . Это продвигает передовые методы управления техническим долгом, которые позволяют вашей команде решать проблемы с техническим долгом.
Оптимизируйте процесс документирования и устранения проблем с техническими долгами в вашей команде с помощью инструмента управления проблемами Stepsize. Это позволяет:
Создание, просмотр и управление задачами в редакторе кода
Преобразование TODO в задачи
Использование мощных инструментов для визуализации технического долга
Понимание того, как технический долг влияет на вашу кодовую базу (и вашу команду)
Получите расширение VSCode здесь или расширение Jetbrains здесь .
Почему они важны и как их использовать
Комментарии в Python — это включение кратких описаний вместе с кодом для повышения его удобочитаемости. Разработчик использует их для описания своего мыслительного процесса при написании кода. Он объясняет основную логику, почему была написана конкретная строка кода. Они просто предназначены для того, чтобы сами программисты или другие разработчики могли понять фрагмент кода, тем более что интерпретатор Python полностью игнорирует комментарии в Python. Вы можете увидеть это в следующем примере.
Комментарии в Python обозначаются символом hash , # и доходят до конца строки. Однако хеш-символы в строке не считаются комментариями. Комментарий можно написать тремя способами: отдельной строкой рядом с соответствующим оператором кода или многострочным блоком комментариев.
Написание комментариев в Python можно использовать по-разному. Некоторые важные области применения включают:

Повышение читабельности
Объяснение кода другим
Легкое понимание кода после длительного обучения
Включая ресурсы
Повторное использование существующего кода
Комментарии в Python предоставляют множество преимуществ. Их основные преимущества включают в себя:
Делает код понятным для других программистов
Код становится понятным
Помогает вспомнить, почему мы использовали определенную команду, метод или функцию в коде
Позволяет интерпретатору игнорировать часть кода при тестировании
Существует три типа комментариев: однострочные, многострочные и комментарии строки документации. Синтаксис комментариев зависит от типа. В этом руководстве мы рассмотрим каждый вид комментариев по отдельности вместе с примерами.

Однострочные комментарии
Однострочные комментарии начинаются с символа «#». Все, что написано одной строкой после «#», считается комментарием. Синтаксис для написания однострочных комментариев:
# комментарии здесь
Существует два способа использования однострочных комментариев в Python. Вы можете использовать его перед кодом или рядом с кодом. В приведенном ниже примере показано использование комментариев обоими способами.
PEP8, Руководство по стилю Python, рекомендует использовать менее 79 символов в однострочном комментарии, чтобы его было легче читать. Если ваш комментарий превышает рекомендуемую длину, вы можете использовать следующий тип: многострочные комментарии.

Многострочные комментарии
Python не поддерживает многострочные комментарии. Однако есть несколько способов решить эту проблему. Ни один из этих способов технически не является многострочным комментарием, но вы можете использовать их как единое целое. Первый способ — использовать # в начале каждой строки комментария.
Следующий способ — использовать строковые литералы, но не присваивать их каким-либо переменным. Если вы не присвоите строковый литерал переменной, интерпретатор Python проигнорирует его. Используйте это в своих интересах, чтобы писать многострочные комментарии. Вы можете использовать одинарную (») кавычку или двойную («») кавычку.

Вы также можете использовать многострочные строки для комментариев. Для этого трижды используйте кавычки «» или «».
Строки документации Python
Python предоставляет встроенную функцию, называемую строками документации, для комментирования модулей, методов, функций, объектов и классов. Они пишутся в первой строке после определения модуля, функции, метода и т. д. с использованием трех кавычек («» или «»). Если вы не используете его в первой строке, интерпретатор не воспримет его как строку документации. Вы также можете получить доступ к строкам документации, используя атрибут __doc__.
Комментарии являются важной частью программы. Поэтому очень важно научиться писать хорошие комментарии. Вот некоторые характеристики, которые определяют хорошие комментарии.
Убедитесь, что они краткие

Не пишите общие комментарии; иметь их только в том случае, если они добавляют информацию
(a=10 # присваивание 10 a, избегайте написания таких общих комментариев)
Пишите комментарии, описывающие общую задачу функции или метода, а не конкретные детали
Хорошие комментарии говорят сами за себя
Не писать лишние комментарии
Хотите перейти в область программирования? Пройдите курс обучения Python и начните свою карьеру профессионального программиста Python
.
Posted in Разное