Pull to refresh
  • by relevance
  • by date
  • by rating

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

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

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

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

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

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

А вот вопрос на каком языке комментировать мне не совсем ясен.
Читать дальше →
Total votes 17: ↑14 and ↓3+11
Views1.3K
Comments 27

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

Lumber room
Если верить в то, что ненависть других людей способна уменьшить вашу жизнь на несколько лет, то программисты, которые обильно комментируют свой код живут как минимум лет на 10 дольше, чем остальные программисты.
Total votes 36: ↑24 and ↓12+12
Views253
Comments 24

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

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

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

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

Designing and refactoringGame development


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

Qt. Кодек. Perestroika

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

Читать дальше →
Total votes 28: ↑10 and ↓18-8
Views3.3K
Comments 1

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

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


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

Читать дальше →
Total votes 70: ↑67 and ↓3+64
Views22K
Comments 20

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

Mail.ru Group corporate blogProgrammingPerfect codeDesigning and refactoringIT Standards
Translation
Tutorial


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

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

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

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

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

В этой статье мы рассмотрим разные аспекты комментирования кода.
Читать дальше →
Total votes 75: ↑67 and ↓8+59
Views37K
Comments 25

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

ua-hosting.company corporate blogWebsite developmentProgrammingDevelopment of mobile applications
Недавно, ковыряя один не особо популярный фреймворк, я наткнулся на следующий кусок кода.


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

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

//Не рекомендуется к прочтению, если Вы не любите пятничные посты во вторник.
Читать дальше →
Total votes 58: ↑52 and ↓6+46
Views26K
Comments 73

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

DebuggingCLifehacks for geeks
Несмотря на простоту (и, в общем-то, тривиальность, если подумать) описываемого решения, наткнулся на него чисто случайно, во время разукрашивания комментарием законченной программы, готовой к сдаче.

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

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

Perfect codeDevelopment Management
Sandbox
Привет! Сегодня я хочу поделиться советами по написанию совершенного понятного кода, взятые из книги Питера Гудлифа «Ремесло программиста // Практика написания хорошего кода».

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

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

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

image

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

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

Designing and refactoringIT Standards
Sandbox
Привет, Хабр! Представляю вашему вниманию перевод статьи «Writing good comments: the why, not the how» автора Jack Franklin.

image

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

Я считаю, что в большинстве случаев такой совет будет неудачным и неверным.
Читать дальше →
Total votes 40: ↑38 and ↓2+36
Views12K
Comments 11

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

ProgrammingSystem Analysis and DesignDesigning and refactoringIT Standards

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

Читать далее
Total votes 21: ↑4 and ↓17-13
Views3.9K
Comments 7

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

Mail.ru Group corporate blogProgrammingSystem Analysis and DesignDesigning and refactoring
Translation
Tutorial

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

Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.
Читать дальше →
Total votes 21: ↑18 and ↓3+15
Views4.4K
Comments 6