Правила программирования на С и С++. Главы 1-6
Страница 32. Комментарии должны быть в блоках
|
|
Страница 32 из 93
28. Комментарии должны быть в блоках.
Комментарии в общем воспринимаются лучше, когда помещаются в многострочных блоках, которые чередуются с блоками текста программы. Для этого комментарий должен описывать на высоком уровне, что делают несколько последующих строк кода. Если комментарии попадаются через строчку, то это похоже на чтение двух книг одновременно, причем по строке из каждой по очереди. И если программа, комментируемая вами, сложная, то вы можете воспользоваться сносками: // Вот блочный комментарий, описывающий последующий блок программы. // После общего резюме я описываю некоторые особенности: // // 1. Этот комментарий описывает, что происходит в строке с меткой 1 // // 2. Этот комментарий описывает, что происходит в строке с меткой 2 // // В точке 1 алгоритм устанавливается на ... // here_is_the_code(); while ( some_condition ) { this_code_is_rather_obscure(); /* 1 */} more_stuff_here(); while ( some_condition ) { this_code_is_also_obscure(); /* 2 */} |