Отладка приложений



         

Комментарии


Однажды мой друг Фрэнсис Полин (Francois Poulin), работавший в службе сопровождения, явился на работу с нагрудной табличкой, которая гласила: "Пиши программы так, будто всякий, кто сопровождает твою программу — полный психопат, который знает, где ты живешь!" Фрэнсис никакой не психопат, но он предложил хорошую идею. Разработчик может, конечно, считать, что его программа — идеал ясности и совершенно понятна без всяких комментариев, но на самом деле она столь же плоха для тех, кто ее сопровождает, как сплошные строки команд ассемблера. Вспоминайте табличку Фрэнсиса каждый раз, когда пишете программу.

Работа инженеров-разработчиков преследует две цели: создать решение для пользователя и сделать его удобным для поддержки в будущем. Единственный способ сделать код удобным для поддержки состоит в том, чтобы комментировать его. "Комментировать" не означает просто записывать комментарии, которые разъясняют, что именно делает программа; имеется в виду документирование предположений, подходов к решению задачи и причин для их выбора. Необходимо также отслеживать соответствие комментариев тексту программы.

Рекомендую следующий подход к комментированию:

  • каждая функция или метод нуждаются в одном-двух предложениях комментариев, которые сообщают:

• что подпрограмма делает;

• какие она использует предположения;

• что она ожидает получить через каждый входной параметр;

• что будет содержать каждый выходной параметр при успехе и отказе;

• каждое возможное возвращаемое значение.

  •  каждая часть функции, которая не полностью очевидна из кода, нуждается в одном или двух предложениях комментариев, которые объясняют, что она делает;
  •  любой интересный алгоритм заслуживает полного описания;
  •  любые нетривиальные ошибки, которые вы исправили в коде, должны быть прокомментированы с указанием номера ошибки и описанием сути исправления;
  •  хорошо расположенные операторы трассировки и утверждений, а также удачные соглашения об именах могут служить отличными комментариями и обеспечивать поддерживающий контекст для кода;
  •  комментируйте так, будто вы собрались сопровождать код в течение пяти лет;
  •  если, просматривая код функции, вы произносите фразы типа: "Это — хакерская штучка" или "Это — действительно хитрый материал", то, вероятно, нужно переписывать функцию, а не комментировать ее.

Различие между серьезным, профессиональным разработчиком и тем, кто играет в него, выявляет надлежащая и полная документация в коде. Дональд Кнут (Donald Knuth) однажды заметил, что хорошо написанную программу нужно уметь читать так же, как хорошо написанную книгу. Хотя я не представляю себя лежащим на ковре у камелька с копией исходного кода программы ТеХ, но я полностью согласен с мнением доктора Кнута.

Рекомендую изучить главу 19 "Self-Documenting Code" феноменальной книги Стива МакКоннелла (Steve McConnell) Code Complete (Microsoft Press, 1993). Читая ее, вы увидите, как я учился писать комментарии. Если вы комментируете правильно, то даже если сопровождающий программист окажется психопатом, не сомневайтесь — вы будете в безопасности.




Содержание  Назад  Вперед