Комментарии 30
Скажите, пожалуйста: "расшили" - это опечатка (и имелось в виду - "расширили")?
Или это так и задумывалось (абзац "«Я бы не сказал, что программисты нарушили те или иные правила. Скорее, они расшили границы передовых методов работы при создании больших языковых моделей, таких как я». ")?
В вопросе правил две крайности:
правило не соблюдается вообще (100% исключений)
правило соблюдается абсолютно (0% исключений)
Второй случай может быть не менее вредным, чем первый. Никакое правило не должно отменять критический подход. А крайности вообще опасная штука.
Создатели языка Go говорят, что хотели создать язык программирования, который можно освоить очень быстро, буквально за день
И судя по тому, что в каждом руководстве по Го имеется тема "слайсы не то, чем кажутся, а горутины тем более" - у них это получилось.
Но горькая правда состоит в том, что иногда комментарии всё только портят. Порой документация не имеет ничего общего с кодом.
Но ведь документация не имеет ничего общего с комментариями в коде? Это две разные сущности. Весь параграф какой-то неправильный, который исходит из того, что документация = комменты.
Наличие или отсутствие документации никак не ограничивает разработчика в комментировании собственного кода. И как бы коротки не были функции, написать в самом начале ЧТО она делает - хорошо и правильно. Даже если эта функция удаляет вторую букву фамилии пользователя каждый третий четверг года - в комментарии так и должно быть написано. А рассказать ПОЧЕМУ она это делает - задача документации.
А я считаю наоборот. Описать, что делает внешний интерфейс и как это использовать - задача документации. ///summary перед методом - это тоже документация.
А вот описать, зачем возникло какое-то неочевидное место - это как раз задача комментария.
А вот описывать, что делает каждая строчка кода - бессмысленно, код сам за себя лучше говорит
Каждую строчку кода описывать и не надо. Документировать саммари с описанием что делает интерфейс - это именно то, что я и написал. Но это не должно быть "Интерфейс предназначен для автоматической обработки инвойсов по запросу от ФНС со ссылкой на оригинальный заказ, в случае если бла-бла-бла" - это предназначено для документации. Это должно быть "Интерфейс обработки инвойса и возврата связанных документов". Причем, в идеале, каждый блок в этом интерфейсе должен быть описан таким же коротким комментарием. Код, конечно, лучше за себя говорит, но комментарии тебе как минимум помогут понять, что делает функция с логикой на 1000 строк раз в 10 быстрее.
Есть очень простое правило: код описывает, что мы делаем, а комментарии описывают, почему мы это делаем.
Например
def some_method
self.some_value = perform_some_calculations()
save! # Если в perform_some_more_calculations() произойдёт ошибка,
# то потеряются *все* результаты вычислений — а мы хотим, чтобы
# в базе остались хотя бы результаты perform_some_calculations(),
# чтобы потом не вычислять их ещё раз
self.some_other_value = perform_some_more_calculations()
save!
end 
Все знают, что разбираться в незадокументированном коде и заниматься его отладкой — это кошмар на улице Вязов.
Документация и комментарии - разные вещи.
Одному моему коллеге нравится применять все новые умные операторы в JavaScript, например, ellipsis
Он появился лет 9 назад - ну совсем недавно :)
Если скорость не так уж критична, имеет смысл писать код, который работает немного медленнее, но в котором проще разобраться.
Код как газ. Заполняет весь предоставленный ему объем.
10 вредных привычек, которые программисты втайне обожают
Мне не нравится ни одна из приведённых привычек. Правда, я и не настоящий программист, так что всё ОК.
По всем этим и не только этим причинам некоторые разработчики считают, что лучше всего не перебарщивать с бесполезными комментариями, а то и вовсе обходиться без них. Вместо этого они отдают предпочтение простым, довольно коротким функциям, в которых в качестве подсказки используют длинные описательные имена переменных а-ля «горбатый регистр». Если компилятор не содержит ошибки, код должен быть наиболее точным отражением того, что делает компьютер.
Типичная ошибка состоит в том, что многие пишут в комментарии, что делает код. Тогда как чаще всего нужно писать зачем он это делает. Понять что, действительно, можно из самого кода.
Сейчас появилось так много умных синтаксических штук, что знать их все просто невозможно. Да и зачем? Сколько способов нужно, чтобы проверить поле на пустое значение или сделать наследование многоуровневым? Неужели только один из этих способов правильный и намного лучше остальных? Конечно, в команде всегда найдётся сотрудник, который устроит скандал по этому поводу и испортит обеденный перерыв или летучку.
Правильно зачем изучать новшества в языке лучше не изучать и через пару лет оказаться в ситуации когда не понимаешь что делает код твоего проекта, да и количество способов проверить поле на пустоту как минимум равно количеству стандартных типов которые поддерживаются языком.
Я бы все перевел к более простой модели: при написании кода нужно соблюдать баланс между читаемостью / разумной утилизацией ресурсов / скоростью разработке. Ну и опыт разработчика помогает найти компромисс.
Переходя дорогу, хорошие программисты смотрят сначала налево, потом направо.
Ну это смотря в какой стране они живут.
Смотря от много чего. Например, незачем смотреть налево, переходя дорогу с односторонним движением справа налево.
Даже на дороге с односторонним движением лучше посмотреть в обе стороны, причем лучше постоянно посматривать в обе стороны (для дороги с двусторонним движением это тоже правильно).
Всякое бывает. И нарушители (в том числе просто перепутавшие), и спецслужбы всякие, которым в исключительных случаях можно нарушать, и всякие нештатные ситуации (например, когда на подъеме автомобиль неожиданно, в том числе для самого водителя, начинает ехать обратно).
На счёт комментариев: они в большинстве случаев обладают существенным недостатком - они могут совершенно не соответствовать тому, что фактически происходит в коде. Часто такое происходит, когда код изменили, а комментарий забыли обновить.
Поэтому по возможности лучше не писать комментарии, а выражать мысли и намерения средствами самого языка - например, используя более ограниченные типы (с соблюдением неких инвариантов). При этом совсем от комментариев отказываться не стоит, но в них не нужно будет указывать то, что и так уже выражено кодом.
я обычно больше обращаю внимание на то кому и что и кому я хочу сказать своими комментариями, например внутренний код я комментариями не покрываю, так как их увидит только другой разработчик, который так же и код прочитает, если он написан просто и понятно, тт комментарии тут не особо нужны, но в некоторых случаях, когда есть не очевидные вещи то добавляю, например алгоритм валидации ИНН или что то такое, но в большинстве случаев я только данные перекладываю из одного поля в другое. Но вот все поля в транспортной библиотеке я описываю, так как они бкдут видны в документации к моему API, для человека, который будет им пользовать и у которого нет доступа к коду. То же казается библиотек, которые я упаковываю в пакеты их апи так же описано
самая вредная привычка программистов использовать топовое железо, да еще и рекомендовать "выбросить старье".
Аналогично и с версиями ОС, хотя это ситуация посложнее, в силу большого разнообразия
Тут просто работает принцип "чужие ресурсы не жалко". Когда за железо платит пользователь, у разработчиков попросту нет мотивации что-то там оптимизировать: работает - и ладно.
А вот когда за вычислительные ресурсы платит сам разработчик (точнее, заказчик проекта) - вот тут-то всё делают как надо.
Скажем, если заглянуть в код современных библиотек машинного обучения, типа pytorch или tensorflow, так просто глаза на лоб начинают лезть от того, сколько усилий там ввалено в оптимизацию и насколько нетривиальные трюки применяются. Причём с каждой версией на том же железе оно работает только быстрее, в отличие от всяких там мессенджеров, в которых уже даже на топовом железе ввод текста ощутимо притормаживает.
Код без комментариев
В своих личных проектах я стараюсь комментировать код (по крайней мере некоторые важные этапы или малопонятные моменты, или описание исправления каких либо странных ошибок, чтобы видеть это снова и снова, чтобы уж точно запомнить и не повторить), но бывает, что пишу разные суровые самопалы чисто для себя, и не комментирую. На предыдущей работе было даже правило, которое ЗАПРЕЩАЕТ комментировать, чтобы никаких комментариев в коде не было, кроме исключительных случаев, чтобы объяснить причину нестандартной ситуации (например, какого-нибудь костыля для какой-то определённой кривой железки). Разрабатывая библиотеки первым делом стараюсь документировать публичные функции Doxygen-форматом, чтобы пользователям библиотеки было понятно, как их использовать.
Автор статьи не читал Чистый код.
некоторые разработчики считают, что лучше всего не перебарщивать с бесполезными комментариями
А другие уверены, что с бесполезными комментариями лучше переборщить, что ли? Безумцы какие-то, не рекомендую таких разработчиков.
10 вредных привычек, которые программисты втайне обожают