html текст
All interests
  • All interests
  • Design
  • Food
  • Gadgets
  • Humor
  • News
  • Photo
  • Travel
  • Video
Click to see the next recommended page
Like it
Don't like
Add to Favorites

О комментариях в коде замолвите слово

Появился пост, в комментариях к которому (какая ирония) было много мнений,
что самый лучший код — self-documenting и все такое.

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


В посте я кратко расскажу, как использую комментарии в своей разработке уже 10 лет и плавно затрону тему документации вообще.

Комментарии помогают найти забытый код


Есть у Артемия Лебедева (мастер эпатажа ИМХО) такое правило — он знает образ своего мышления. И если забыл что-то, например, где нужная фотка лежит, то знание системы категоризации своей позволяет найти быстро нужную фотку.

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

Комментарии помогают разрабатывать в IDE


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

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


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

Документация вообще


Мне, спустя года, стало нравится высказывание «лень — двигатель прогресса». Считаю, ленивый программист или админ — это врожденное и полезное качество.

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

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

Через полгода на 80% я отвечал ссылками на туториалы и FAQ и не выходил из потока, хотя количество моих подчиненных выросло на проектах от двух до пяти.

Вывод


Если вы работаете один, если у вас масса времени, если вы не делаете проекты в промышленном масштабе — то можно писать красивый самодокументирующийся код. Я так делал в своих поделках до поры до времени.

Можно писать хороший читаемый код, но для восприятия проекта в целом и решения практических задач, изложенных выше, комментарии полезны.

Если вы работаете в команде, у вас есть проекты, которые вырастут до >100,000 строк кода, и вы будете возвращаться к ним через пару лет — комментарии вам просто необходимы. Хотя бы на уровне, что делает тот или иной файл, тот или иной большой важный кусок логики.

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

Особенно актуально после принятия проектов от нубов, которые прочитали Макконнелла про самодокументирующийся код и запомнили, что комментарии писать не надо, а все остальные рекомендации к оформлению кода и code conventions проигнорировали напрочь — или, не дай Бог, фриланс-заказ из прошлого по поддержке индусского сайта).

А если еще при этом вы является Senior, Team Lead разработчиком, и в ваши обязанности входит еще и работа с нетехническими людьми, либо работа с новичками — то документация, наращиваемая по эволюционному принципу on-demand для повышения, так сказать, cache hit raio, станет существенной экономией вашего времени.

Ссылки в тему
1.There is No Such Thing as Self-Documenting Code – It’s a Myth

2. Bloated names, and the myth of self-documenting code

3. Intent versus action, or the myth of self-documenting code

4. Self Documenting Code and other Myths
Читать дальше
Twitter
Одноклассники
Мой Мир

материал с habrahabr.ru

2

      Add

      You can create thematic collections and keep, for instance, all recipes in one place so you will never lose them.

      No images found
      Previous Next 0 / 0
      500
      • Advertisement
      • Animals
      • Architecture
      • Art
      • Auto
      • Aviation
      • Books
      • Cartoons
      • Celebrities
      • Children
      • Culture
      • Design
      • Economics
      • Education
      • Entertainment
      • Fashion
      • Fitness
      • Food
      • Gadgets
      • Games
      • Health
      • History
      • Hobby
      • Humor
      • Interior
      • Moto
      • Movies
      • Music
      • Nature
      • News
      • Photo
      • Pictures
      • Politics
      • Psychology
      • Science
      • Society
      • Sport
      • Technology
      • Travel
      • Video
      • Weapons
      • Web
      • Work
        Submit
        Valid formats are JPG, PNG, GIF.
        Not more than 5 Мb, please.
        30
        surfingbird.ru/site/
        RSS format guidelines
        500
        • Advertisement
        • Animals
        • Architecture
        • Art
        • Auto
        • Aviation
        • Books
        • Cartoons
        • Celebrities
        • Children
        • Culture
        • Design
        • Economics
        • Education
        • Entertainment
        • Fashion
        • Fitness
        • Food
        • Gadgets
        • Games
        • Health
        • History
        • Hobby
        • Humor
        • Interior
        • Moto
        • Movies
        • Music
        • Nature
        • News
        • Photo
        • Pictures
        • Politics
        • Psychology
        • Science
        • Society
        • Sport
        • Technology
        • Travel
        • Video
        • Weapons
        • Web
        • Work

          Submit

          Thank you! Wait for moderation.

          Тебе это не нравится?

          You can block the domain, tag, user or channel, and we'll stop recommend it to you. You can always unblock them in your settings.

          • habrahabr.ru
          • домен habrahabr.ru

          Get a link

          Спасибо, твоя жалоба принята.

          Log on to Surfingbird

          Recover
          Sign up

          or

          Welcome to Surfingbird.com!

          You'll find thousands of interesting pages, photos, and videos inside.
          Join!

          • Personal
            recommendations

          • Stash
            interesting and useful stuff

          • Anywhere,
            anytime

          Do we already know you? Login or restore the password.

          Close

          Add to collection

             

            Facebook

            Ваш профиль на рассмотрении, обновите страницу через несколько секунд

            Facebook

            К сожалению, вы не попадаете под условия акции