Как стать автором
Обновить

Комментировать или не комментировать?

Совершенный код *
«Ясно, что на некотором уровне комментарии должны быть полезны. Думать иначе означало бы полагать, что понятность программы не зависит от того, сколько информации о ней уже известно читающему программу человеку. Б. Шейл.»
Действующие лица:
ФРАСИМАХ Неопытный пурист теории, который верит всему, что читает.
КАЛЛИКЛ Закаленный в боях представитель старой школы — «настоящий»
программист.
ГЛАВКОН Молодой, самоуверенный, энергичный программист.
ИСМЕНА Опытная разработчица, уставшая от громких обещаний и просто
желающая найти несколько работающих методик.
СОКРАТ Мудрый опытный программист.

Мизансцена:
Завершение ежедневного собрания группы
— Желает ли кто-то обсудить еще что-нибудь, прежде чем мы вернемся к работе? — спрашивает Сократ.
— Я хочу предложить стандарт комментирования для наших проектов, — говорит расимах. — Некоторые наши программисты почти не комментируют свой код, а всем известно, что код без комментариев нечитаем.
— Ты, должно быть, еще менее опытен, чем я думал, — отвечает Калликл. — Комментарии — это академическая панацея, и любому, кто писал реальные программы, известно, что комментарии затрудняют чтение кода, а не облегчают. Естественный язык менее точен, чем Java или Visual Basic, и страдает от избыточности, тогда как операторы языков программирования лаконичны и попадают в самое яблочко. Если кто-то не может написать ясный код, разве ему удастся написать ясные комментарии? Кроме того, комментарии устаревают при изменениях кода.
Доверяя устаревшим комментариям, ты сам себе роешь яму.
Читать дальше →
Всего голосов 14: ↑10 и ↓4 +6
Просмотры 1.1K
Комментарии 12

Комментирование кода русским языком

Чулан
Вопрос комментировать или не комментировать код для меня вполне понятен, стараюсь придерживаться правил:

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

А вот вопрос на каком языке комментировать мне не совсем ясен.
Читать дальше →
Всего голосов 17: ↑14 и ↓3 +11
Просмотры 2K
Комментарии 27

Комментирование кода и продолжительность жизни

Чулан
Если верить в то, что ненависть других людей способна уменьшить вашу жизнь на несколько лет, то программисты, которые обильно комментируют свой код живут как минимум лет на 10 дольше, чем остальные программисты.
Всего голосов 36: ↑24 и ↓12 +12
Просмотры 310
Комментарии 24

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

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

Сам топик решил написать после того, как мне пришлось усовершенствовать несколько своих старых программ. В частности столкнулся с тем, что когда их писал не дал должного внимания написанию комментариев и в результате прошло 4 года и я наступил на свои грабли, потратив лишнее время на разбор своего старого кода. Поэтому и родился этот топик, дабы акцентироваться на важности комментариев в коде. Были сделаны выводы, которыми делюсь ниже.
Читать дальше →
Всего голосов 19: ↑12 и ↓7 +5
Просмотры 9.8K
Комментарии 13

Почему Pinball убрали из Windows Vista

Проектирование и рефакторинг *Разработка игр *


Один из разработчиков Microsoft объяснил, почему замечательную игру Pinball не включили в состав Windows Vista. Ходили слухи, что это было сделано по юридическим причинам. Но нет, причины сугубо технические. Оказывается, Pinball просто не смогли портировать 64-битную платформу.
Читать дальше →
Всего голосов 222: ↑203 и ↓19 +184
Просмотры 173K
Комментарии 174

Qt. Кодек. Perestroika

Программирование *Qt *
Qt PerestroikaПривет. Появилась необходимость залезть в исходники QTextCodec (как следует из названия, класса Qt для работы с текстовыми кодеками), увидел довольно забавный кусок кода — как только не приходится извращаться разработчикам чтобы обеспечить корректную работу у огромного количества пользователей со всего мира.

Читать дальше →
Всего голосов 28: ↑10 и ↓18 -8
Просмотры 3.4K
Комментарии 1

Sir Markdown. Лекция Яндекса

Блог компании Яндекс Совершенный код *GitHub *Локализация продуктов *Подготовка технической документации *
При разработке документации мы руководствуемся не только стандартами, но и удобством её использования. Стандарты определяют состав и форму документации, а формат строится исходя из удобства. Разработчик Сергей Бочаров рассказывает о пути Markdown-документа и о проблемах, которые приходится решать в обмен на простоту использования этого формата.


У меня иногда складывается впечатление, что не он служит для нас, а мы служим для этого формата. Поэтому — сэр Markdown.

Всего голосов 70: ↑67 и ↓3 +64
Просмотры 24K
Комментарии 20

Комментирование кода: хороший, плохой, злой

Блог компании VK Программирование *Совершенный код *Проектирование и рефакторинг *IT-стандарты *
Перевод
Tutorial


Вы наверняка это слышали: «Хороший код является самодокументированным».

Я больше 20 лет зарабатываю написанием кода, и слышал эту фразу чаще всего. Это клише.

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

Она истинна? Да.

Означает ли она, что вы никогда не должны комментировать код? Нет.

В этой статье мы рассмотрим разные аспекты комментирования кода.
Читать дальше →
Всего голосов 75: ↑67 и ↓8 +59
Просмотры 40K
Комментарии 25

Комментарии в коде как способ самовыражения

Блог компании ua-hosting.company Разработка веб-сайтов *Программирование *Разработка мобильных приложений *
Недавно, ковыряя один не особо популярный фреймворк, я наткнулся на следующий кусок кода.


Потому что роботы-убийцы любят единорогов!

Не знаю, какую мысль и в каком настроении хотел донести автор, но это навело меня на размышления: как часто мы используем комментарии не совсем по назначению? Немного находок под катом.

//Не рекомендуется к прочтению, если Вы не любите пятничные посты во вторник.
Читать дальше →
Всего голосов 58: ↑52 и ↓6 +46
Просмотры 26K
Комментарии 73

Выключка кода комментарием: маленький лайфхак

Отладка *C *Лайфхаки для гиков
Несмотря на простоту (и, в общем-то, тривиальность, если подумать) описываемого решения, наткнулся на него чисто случайно, во время разукрашивания комментарием законченной программы, готовой к сдаче.

В программистской практике регулярно случается ситуация, когда на время разработки и отладки требуется включать какой-то код и выключать другой. Это несложно делать специальными конструкциями типа #if true ... #else ... #endif, меняя true на false, или прибегая к более изощренным условиям.
Читать дальше →
Всего голосов 30: ↑7 и ↓23 -16
Просмотры 5.2K
Комментарии 33

10 принципов самодокументируемого кода

Совершенный код *Управление разработкой *
Из песочницы
Привет! Сегодня я хочу поделиться советами по написанию совершенного понятного кода, взятые из книги Питера Гудлифа «Ремесло программиста // Практика написания хорошего кода».

Конечно, неплохо было бы прочитать эту занимательную книгу каждому кто пишет код, но для особо ленивых, но желающих перестать меньше мучить и вводить коллег в заблуждение (совесть имейте) представляю под катом 10 принципов самодокументируемого кода:
Читать дальше →
Всего голосов 61: ↑49 и ↓12 +37
Просмотры 38K
Комментарии 134

Как развивались комментарии к коду с 1940-х до 2020 года

Программирование *
Recovery mode
Из песочницы
А никак они не развивались. С самых первых языков программирования и по сей день комментарии коду — это всего лишь статичный текст (за некоторыми исключениями, о которых я расскажу).

image

Ну а что там еще можно улучшить или придумать — спросите вы. Давайте поразмышляем на эту тему — можно ли как-то улучшить наш опыт взаимодействия с таким важным но так часто игнорируемым аспектом программирования как документация в коде, или по-простому комментарии.
Читать дальше →
Всего голосов 45: ↑33 и ↓12 +21
Просмотры 9.8K
Комментарии 26

Как писать хорошие комментарии к коду: «зачем», а не «как»

Проектирование и рефакторинг *IT-стандарты *
Из песочницы
Привет, Хабр! Представляю вашему вниманию перевод статьи «Writing good comments: the why, not the how» автора Jack Franklin.

image

Комментирование кода в программистской среде нередко считается пустой тратой времени или неким сигналом о том, что код можно и улучшить. Вот цитата из файла CONTRIBUTING.md, который я нашёл на Гитхабе (и таких примеров очень, очень много):
Комментариев следует избегать. Если ваш код нельзя понять без комментариев, перепишите его так, чтобы он сам себя объяснял.

Я считаю, что в большинстве случаев такой совет будет неудачным и неверным.
Читать дальше →
Всего голосов 40: ↑38 и ↓2 +36
Просмотры 13K
Комментарии 11

Хороший, плохой, злой комментарий

Программирование *Анализ и проектирование систем *Проектирование и рефакторинг *IT-стандарты *

Зачем нужны комментарии. Правда ли, что хороший код должен быть без них и как команды замедляют разработку в 4 раза, забывая о "смысле жизни".

Читать далее
Всего голосов 21: ↑4 и ↓17 -13
Просмотры 4.1K
Комментарии 7

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

Блог компании VK Программирование *Анализ и проектирование систем *Проектирование и рефакторинг *
Перевод
Tutorial

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

Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.
Читать дальше →
Всего голосов 34: ↑31 и ↓3 +28
Просмотры 9.3K
Комментарии 6