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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При написании даже несуществующего адреса электронной почты нужно соблюдать правила именования адресов. Например, в адресе [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?

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

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

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

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

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

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

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

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

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

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

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

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

Комментарии / Устройство сайта / Хабр

Комментарии и действующие ограничения

Комментировать публикации могут только зарегистрированные пользователи. Владельцы учётных записей с правами Read&Comment могут оставлять комментарии только к новым публикациям (не старше 30 дней) и только с премодерацией: первые 10 комментариев должны пройти проверку 10 разными авторами или модераторами. Премодерация осуществляется в основном авторами комментируемых публикаций — им проще оценивать компетентность или уместность комментария, так как они с большей вероятностью разбираются в теме поста лучше модераторов.

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

Чтение комментариев

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

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

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

Цветовая индикация комментариев

Шапки комментариев могут иметь следующую подсветку:

• Жёлтый — ваши собственные комментарии

• Зелёный — комментарии автора публикации

• Синий — новые комментарии (перекрывает предыдущие случаи)

• Красный — комментарии на модерации (видны только авторам публикаций и модераторам)

Редактирование и удаление комментариев

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

Удалить опубликованный комментарий могут только модераторы и только в случае выявления факта нарушения правил сайта. Если под удаляемым комментарием есть другие комментарии, то удаляется вся ветка. Если у модераторов есть возможность устранить нарушение, не удаляя и не искажая смысла комментария, они могут внести правки в текст комментария (но санкции к автору-нарушителю всё равно могут примениться).

Если удаляется не отдельно взятый комментарий, а аккаунт пользователя (как правило, происходит это по запросу самого пользователя), то все размещённые с удалённого аккаунта комментарии заменяются фразой «НЛО прилетело и опубликовало эту надпись здесь». При этом ветки обсуждения, в которых они присутствовали, сохраняются.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, если вы этого хотите. Узнайте, как начать работу с этим революционным инструментом, здесь. Этот инструмент позволит вам:

• Преобразовать TODO в задачи одним щелчком
• Отметьте задачи и проблемы в PR
• Визуализируйте проблемы и технический долг в различных частях вашей кодовой базы
• Сделайте управление проблемами простым для инженеров
• Станьте героем технического долга!

Такие инструменты, как Stepsize, могут очищать TODO и управлять проблемами

3. Выберите и задокументируйте соглашения.

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

Возможно, вы программируете на языке с помощью инструмента компиляции документов, такого как Javadoc для Java, godoc для Go! Или Doxygen для C++. Используйте их — хотя они и не идеальны, структурные преимущества перевешивают недостатки.

Выбирайте инструменты и методы решения проблем, интуитивно понятные для отдельных инженеров и приносящие пользу команде. Вы запрещаете TODO в `main` или у вас есть политика документирования проблем? Убедитесь, что это все понимают.

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

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

Округление

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

Когда мы делаем это правильно, мы не просто облегчаем понимание другим. Мы:

• Ускорение разработки
• Улучшение качества кода
• Повышение морального духа команды
• Управление и устранение технического долга
20002 Во-первых, когда мы пишем хорошие комментарии, мы постоянно выявляем важную информацию об особенностях кода и архитектурных решениях.

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

Оптимизируйте процесс документирования и устранения проблем с техническими долгами в вашей команде с помощью инструмента управления проблемами Stepsize. Это позволяет:

• Создание, просмотр и управление задачами в редакторе кода
• Преобразование TODO в задачи
• Использование мощных инструментов для визуализации технического долга 
• Понимание того, как технический долг влияет на вашу кодовую базу (и вашу команду) ищете надежное решение для управления техническим долгом в вашей инженерной команде, вам нужен Stepsize. Это первый и единственный в мире специализированный инструмент управления техническим долгом. А поскольку он интегрируется с Jira, он понравится и вашему менеджеру проектов.

  ‍Узнайте, как начать работу с Stepsize, здесь. Он работает с Visual Studio, VS Code, JetBrains.
  

  Как правильно писать комментарии ✔ | by Abhay Parashar

  Передовой опыт, которому следует следовать и повышать уровень кодирования

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

  Комментарии важны для кода. Иногда мы непреднамеренно пишем плохие комментарии или бесполезные комментарии, от которых нет никакой пользы. Пример:

   num = 10  ##Присвоение num значения 10  

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

   taxoil = 1,10  ## Определение 10% налога на нефть  
   taxcoal = 1. 30  ## определение налога на уголь в размере 30%0019 добавлять комментарии только к тем строкам кода, их назначение неочевидно   .
   Базовый комментарий Python начинается с одного  #  . Строка за  #  не будет восприниматься интерпретатором как код. Чтобы быть точным, комментарий может быть написан тремя способами — полностью на отдельной строке, рядом с оператором кода и в виде многострочного блока комментариев.
   Однострочный комментарий можно сделать с помощью  # , за которым следует текст, содержащий описание строки.
   Вы также можете написать комментарий рядом с некоторым утверждением.
   Многострочные комментарии можно сделать двумя способами: использовать несколько  #  или использовать  """ """  Docstrings.
   
   Ниже приведен пример нескольких комментариев с использованием  # 
   Теперь давайте рассмотрим пример многострочных комментариев с использованием  """ """  Docstrings.
   Всегда лучше начинать с комментария в вашей программе. Сначала включите работу кода, который вы пишете, а затем в следующей строке напишите об ожидаемом результате кода. Затем напишите несколько строк о разработчиках кода. Напишите об их личной информации и адресе или некоторых социальных ссылках для связи. Затем в следующей строке напишите обо всей имеющейся у вас лицензионной информации, а в конце просто добавьте адрес электронной почты справки или контактную информацию, чтобы связаться с разработчиком в случае любой ошибки.
   
   Функции — это набор инструкций, написанных вне основного кода и используемых при необходимости. Функции очень удобны в использовании, и большинство разработчиков Python предпочитают функции классам. Написание комментариев в функции немного отличается.
   В первой строке нужно написать краткое описание того, что делает функция. Затем в следующих нескольких строках укажите все аргументы функции. Затем вы должны указать некоторую информацию о типе возвращаемого значения функции и в конце несколько заметок, которые вы хотите добавить для своих читателей или для себя в будущем.