Стив Макконнелл - Совершенный код. Мастер-класс

высосаны из пальца, потому что трудно описать что#то настолько простое,
как CopyString, на уровне детальности между «копированием строки» и самим ко#
дом. Предположения об интерфейсе и история изменений также бесполезны —
эти комментарии только занимают место в листинге. Фамилия автора дополнена
избыточными данными, которые можно легко найти в системе управления реви#
зиями. Заставлять указывать всю эту информацию перед каждым методом — зна#
чит подталкивать программистов к написанию неточных комментариев и затруд#
нять сопровождение программы. Эти лишние усилия не окупятся никогда.
Другая проблема с тяжеловесными заголовками методов состоит в том, что они
мешают факторизовать код: затраты, связанные с созданием нового метода, так
велики, что программисты будут стремиться создавать меньше методов. Конвен#
ции кодирования должны поощрять применение хороших методик — тяжеловес#
ные заголовки методов поощряют их игнорировать.
А теперь нескоько советов по комментированию методов.
Располагайте комментарии близко к описываемому ими коду Одна из при#
чин того, что пролог метода не должен содержать объемной документации, в том,
что при этом комментарии далеки от описываемых ими частей метода. Если ком#
ментарии далеки от кода, вероятность того, что их не будут изменять вместе с кодом
при сопровождении, повышается. Смысл комментариев и кода начинает расхо#
диться, и внезапно комментарии становятся никчемными. Поэтому соблюдайте

ГЛАВА 32 Самодокументирующийся код

789

Принцип Близости и располагайте комментарии как можно ближе к описывае#
мому ими коду. Тогда их будут поддерживать, а они сохранят свою полезность.
Несколько компонентов, которые по мере необходимости следует включать в
прологи методов, описаны ниже. Ради удобства создавайте стандартизованные
прологи. Не думайте, что перед каждым методом нужно указывать всю информа#
цию. Включайте действительно важные элементы и опускайте остальные.
Описывайте каждый метод одним'двумя предложе'
Перекрестная ссылка Удачный
ниями перед началом метода Если вы не можете опи#
выбор имени метода — важнейсать метод одним или двумя краткими предложениями, вам,
ший аспект документирования
методов (см. раздел 7.3).
вероятно, следует лучше обдумать роль метода. Если крат#
кое описание придумать трудно, значит, проект метода не
так хорош. Попробуйте перепроектировать метод. Краткое резюмирующее пред#
ложение должно присутствовать почти во всех методах, кроме простых методов
доступа Get и Set.
Документируйте параметры в местах их объявления Самый простой спо#
соб документирования входных и выходных переменных — написать коммента#
рии после их объявления:

Пример документирования входных и выходных данных
в местах их объявления — хороший подход (Java)
public void InsertionSort(
int[] dataToSort, // массив элементов, подлежащих сортировке
int firstElement, // индекс первого сортируемого элемента (>=0)
int lastElement
// индекс последнего сортируемого элемента (=0)
* @param lastElement индекс последнего сортируемого элемента ( --">