Некоторые программисты помещают комментарий в конце каждо% го блока управления, например пишут // end if (a < 1) после за% крывающей скобки оператора if. Это избыточный вид коммента% рия; его приходится отметать, чтобы действительно понять код. Ко% нец блока должен располагаться на той же странице, где его нача% ло, а форматирование должно быть таким, чтобы начало и конец были четко видны. Любых лишних слов нужно избегать.

На практике

Проиллюстрируем принципы комментирования следующим приме% ром. Рассмотрим фрагмент кода C++. Даже если не критиковать идио% матическую сторону, код не вполне понятен.

for (int i = 0; i < wlst.sz(); ++i) k(wlst[i]);

Да, здесь можно кое%что улучшить, чем мы и займемся. Код станет ме% нее загадочным, если применить к нему разумное форматирование и до% бавить немного комментариев:

// Итерация по всем виджетам в списке for (int i = 0; i < wlst.sz(); ++i)

{

// Выведем этот виджет k(wlst[i]);

}

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

for (int i = 0; i < widgets.size(); ++i)

{

printWidget(widgets[i]);

}