Найти: на
Комментарии в коде, часть 1
Подпишитесь на новости



Внимание! Сайт переехал на http://бизнесплюспермь.рф

Разработка программ: комментарии в коде, часть 2.

В этой статье мы рассмотрим комментирование управляющих структур и методов.

Комментарии управляющих структур

Самое подходящее место для комментирования управляющей структуры - предшествующие ей строки. Если это условный оператор, то в комментарии можно пояснить условие и результаты. Если это цикл, можно указать его цель.

Комментарии в конце цикла, условного оператора полезны для обозначения длинных операторов и для пояснения их вложенности.

Пишите комментарии перед каждым условным оператором (Если, If, Case и пр.), перед каждым циклом (Пока, Для каждого, While, …) или группой операторов. Эти конструкции часто требуют пояснения, а место перед ними лучше всего подходит для этого. Используйте комментарии для пояснения цели управляющих структур.

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

Такая методика дополняет визуальную информацию о логической структуре кода, предоставляемую отступами. Если циклы коротки, а вложенности нет, это методика не нужна.

Рассматривайте комментарии в концах управляющих операторов как предупреждения о сложности кода. Подумайте, может следует упростить код?

Комментирование методов

Часто дается совет: независимо от сложности (размера) метода необходимо перед его началом необходимо привести подробнейшее описание, с входными данными и выходными, целью и алгоритмом, телефоном автора и адресом и т.д. Нередко это делается для простых методов, вся суть которых видна из названия. Весь метод - три строки и шапка перед ним десять. ЗАЧЕМ? Это лишние усилия и они не окупятся. Кроме того тяжеловесные заголовки заставляют программистов создавать меньше методов.

Располагайте комментарии по возможности ближе к описываемому коду. Одна из причин того, что шапка метода не должна содержать объемных комментариев в том, что при этом комментарии далеки от описываемых ими частей кода. Если комментарии далеки от кода, вероятность того, что их не будут изменять вместе с кодом при сопровождении, повышается. Смысл комментариев и кода начинает расходится, и внезапно комментарии становятся никчемными. Располагайте комментарии близко к коду и тогда их будут поддерживать, а они сохранят свою полезность. Ни к чему указывать всю информацию перед каждым методом, включайте действительно важные элементы, и пропускайте остальные.

Описывайте каждый метод одним-двумя предложениями перед началом метода. Если не можете описать метод одним или двумя краткими предложениями, вам, вероятно, следует лучше обдумать роль метода. Если краткое описание придумать трудно, значит, проект метода не так хорош. Попробуйте перепроектировать метод. Краткое резюмирующее предложение должно присутствовать во всех методах, кроме простых.

Документируйте параметры в местах их объявления. Самый простой способ - написать комментарии после их объявления:

Функция ПериодыПересекаются(
	Период1, // Значение – структура описывающая период
	Период2, // Значение – структура описывающая период
)

Здесь мы применили комментарии в концах строк. Хоть мы и решили ранее, что их лучше избегать, в данном примере они очень полезны. Кроме того, если названия переменных достаточно выразительны, их можно не комментировать.

Проведите различия между входными и выходными данными. Знать, какие данные являются входными, а какие выходными полезно. Иногда это ясно из контекста, например в Visual Basic выходным данным предшествует ключевое слово ByRef, а входным - ByVal. В C++ указатель объявляется через звездочку, что удобно для выходных данных. Но все же, как правило, лучше идентифицировать входные и выходные параметры явно. Если методы коротки и поддерживается явное различие между входными и выходными данными, документировать статус данных (входной или выходной) наверное не нужно. Однако если метод объемен, указание статуса поможет всем, кто будет читать код метода.

Документируйте предположения. Если вы сделали какие-либо предположения о состоянии получаемых переменных (о допустимых и недопустимых значениях, о том, что массивы должны быть отсортированы, что данные должны быть инициализированы или должны иметь только допустимые значения и т.д.) укажите это или в прологе метода, или в месте объявления данных. Этот вид документации должен присутствовать почти в каждом методе.

Убедитесь, что задокументировали используемые глобальные данные.

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

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

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

/**

Это позволяет перескакивать с метода на метод путем поиска символов /**. Похожая методика заключается в использовании разных маркеров, для разных видов комментариев, в зависимости от того, что они описывают.

В платформе 1С версии 8 редактор кода автоматически скрывает тесты методов, оставляя лишь первую строку метода и комментарий перед ним. Поэтому маркеры можно использовать для обозначения групп методов, например:
////////////////////////////////////////////////
// РАБОТА С ТОРГОВЫМ ОБОРУДОВАНИЕМ
////////////////////////////////////////////////


Прокомментировать статью можно здесь

Hosted by uCoz