Появился быстрый , в комментариях к которым (какая ирония) было много мнений, что лучший код — самодокументируемый и все такое.
В общем, я не претендую на роль гуру и ниже высказываю лишь собственное мнение.
Это отличается от мнения, что лучший комментарий — это тот, который не был сделан, но содержит в себе практические аргументы.
В этом посте я кратко расскажу, как уже 10 лет использую комментарии в своей разработке и постепенно затрону тему документации в целом.
Комментарии помогут найти забытый код
У Артемия Лебедева (ИМХО мастер эпатажа) есть такое правило - он знает свой образ мышления.А если вы что-то забыли, например, где находится нужная вам фотография, то знание вашей системы категоризации позволяет быстро найти нужную фотографию.
То же самое и с комментариями.
У меня есть проекты, к которым не прикасались много лет. Вы открываете этот проект в IDE, вводите несколько слов и без труда находите нужные файлы и классы.
То есть первая тема — в самом начале написать, что хотя бы делает каждый файл.
Экономит много времени на поиск.
А когда есть еще и тесты, поиск совсем упрощается.
Комментарии помогают развиваться в IDE
IDE спроектированы таким образом, что они хранят в памяти все виды javadoc. А когда вы пишете новый код, всплывающие подсказки очень облегчают жизнь, объясняя, что и как.Особенно, когда над проектом работает команда и вы используете сторонние методы.
Комментарии помогают в создании документации.
Не знаю как вам, а мне всегда нравилось документация, созданная на основе комментариев, например справочник.
Когда вы что-то проектируете, может быть очень удобно посмотреть тот или иной метод в чужой библиотеке, не открывая весь код.
Документация в целом
Спустя годы мне стала нравиться поговорка: «лень — двигатель прогресса».Я считаю, что ленивый программист или администратор — это врожденное и полезное качество.
Под ленью я подразумеваю интуитивное желание не выполнять одну и ту же работу более конечного числа раз.
Например, загрузив Apache трижды, на четвертый хороший админ устранит суть проблемы или автоматизирует процесс.
Или в четвертый раз, вручную отредактировав конфиг на пяти серверах, он установит автоматическое распределение конфигов по серверам.
Без этого качества админ каждый раз будет делать рутину.
Когда мне дали несколько загруженных проектов, где очень часто возникали вопросы от разработчиков, я начал применять принцип трех гвоздей.
После третьего запроса я написал FAQ по каждому типовому вопросу, а для каждой задачи — туториал с комментариями в коде туториала.
Через шесть месяцев я в 80% случаев отвечал ссылками на туториалы и часто задаваемые вопросы и не покидал поток.
, хотя количество моих подчиненных на проектах выросло с двух до пяти.
Заключение
Если вы работаете один, если у вас много времени, если вы не занимаетесь проектами в промышленных масштабах, то вы можете написать красивый, самодокументируемый код. Я пока сделал это в своих поделках.Вы можете написать хороший, читаемый код, но для понимания проекта в целом и решения практических задач, изложенных выше, комментарии полезны.
Если вы работаете в команде, у вас есть проекты, которые вырастут до > 100 000 строк кода и вы вернетесь к ним через пару лет, комментарии просто необходимы.
По крайней мере, на уровне того, что делает тот или иной файл, тот или иной большой важный кусок логики.
И, конечно, не забывайте о Эффект Даннига-Крюгера .
Человек может считать свой код читабельным и понятным, но не факт, что это так для других.
Особенно актуально после принятия проектов от нубов , который читал МакКоннелла о самодокументируемом коде и вспомнил, что комментарии писать не надо, и полностью проигнорировал все остальные рекомендации по дизайну кода и конвенциям кода - или, не дай Бог, заказ фрилансера из прошлого на поддержку индийского сайта) .
А если вы при этом Senior, Team Lead разработчик, и в ваши обязанности входит также работа с нетехническими людьми, или работа с новичками, то документация, выстроенная по эволюционному принципу по требованию, Увеличение, так сказать, кэш-рейо попаданий, будет существенной экономией вашего времени.
Ссылки на тему 1. Самодокументируемого кода не существует – это миф 2. Раздутые имена и миф о самодокументируемом коде 3. Намерение против действия, или миф о самодокументируемом коде 4. Самодокументирующийся код и другие мифы Теги: #комментарии #документация #промышленное развитие #программирование
-
Обучение Сертификации Sql Server
19 Oct, 24 -
Облачный Сервис Parse И Intel Edison
19 Oct, 24 -
Почтовка Или Диагностический Ликбез
19 Oct, 24 -
Opera 9.62 Против Opera 10.0 Альфа 1
19 Oct, 24 -
Google Adsense Выйдет На Улицы
19 Oct, 24
