Однажды мой друг Фрэнсис Полин
Однажды мой друг Фрэнсис Полин (Francois Poulin), работавший в службе сопровождения, явился на работу с нагрудной табличкой, которая гласила: "Пиши программы так, будто всякий, кто сопровождает твою программу — полный психопат, который знает, где ты живешь!" Фрэнсис никакой не психопат, но он предложил хорошую идею. Разработчик может, конечно, считать, что его программа — идеал ясности и совершенно понятна без всяких комментариев, но на самом деле она столь же плоха для тех, кто ее сопровождает, как сплошные строки команд ассемблера. Вспоминайте табличку Фрэнсиса каждый раз, когда пишете программу.
Работа инженеров-разработчиков преследует две цели: создать решение для пользователя и сделать его удобным для поддержки в будущем. Единственный способ сделать код удобным для поддержки состоит в том, чтобы комментировать его. "Комментировать" не означает просто записывать комментарии, которые разъясняют, что именно делает программа; имеется в виду документирование предположений, подходов к решению задачи и причин для их выбора. Необходимо также отслеживать соответствие комментариев тексту программы.
Рекомендую следующий подход к комментированию:
- каждая функция или метод нуждаются в одном-двух предложениях комментариев, которые сообщают:
• какие она использует предположения;
• что она ожидает получить через каждый входной параметр;
• что будет содержать каждый выходной параметр при успехе и отказе;
• каждое возможное возвращаемое значение.
- каждая часть функции, которая не полностью очевидна из кода, нуждается в одном или двух предложениях комментариев, которые объясняют, что она делает;
- любой интересный алгоритм заслуживает полного описания;
- любые нетривиальные ошибки, которые вы исправили в коде, должны быть прокомментированы с указанием номера ошибки и описанием сути исправления;
- хорошо расположенные операторы трассировки и утверждений, а также удачные соглашения об именах могут служить отличными комментариями и обеспечивать поддерживающий контекст для кода;
- комментируйте так, будто вы собрались сопровождать код в течение пяти лет;
- если, просматривая код функции, вы произносите фразы типа: "Это — хакерская штучка" или "Это — действительно хитрый материал", то, вероятно, нужно переписывать функцию, а не комментировать ее.
Рекомендую изучить главу 19 "Self-Documenting Code" феноменальной книги Стива МакКоннелла (Steve McConnell) Code Complete (Microsoft Press, 1993). Читая ее, вы увидите, как я учился писать комментарии. Если вы комментируете правильно, то даже если сопровождающий программист окажется психопатом, не сомневайтесь — вы будете в безопасности.
