Элементы стиля программирования 1 Комментирование кода 2

Элементы стиля программирования. 1

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

ü Комментарии должны быть законченными смысловыми предложениями ü Комментарии должны соответствовать программному коду ü Комментарии должны документировать физический процесс Примеры комментариев /-----------------//производим масштабирование. . . . /-----------------// вычисляем среднее значение за период. . . . 3

üКомментарии должны иметь тот же отступ, что и окружающий текст программы void the_function( void ) { //размер массива int size = 10; int a, b //массив сортируемых чисел int arr[size]; while ( a < b ) { //проверка на наличие чего либо while ( something_else() ) { for ( i = 10; i >= 0; i-- ) { //обработка массива arr[i] = some_fun(i); } } 4

üКомментарии должны иметь тот же отступ, что и окружающий текст программы void the_function( void ) { //размер массива int size = 10; int a, b //массив сортируемых чисел int arr[size]; while ( a < b ) { //проверка на наличие чего либо while ( something_else() ) { for ( i = 10; i >= 0; i-- ) { //обработка массива arr[i] = some_fun(i); } } 5

üКомментарии могут идти параллельно тексту программы void the_function( void ) { int size = 10; int a, b, i; int arr[size]; // размер массива // вспомогательные переменные // массив сортируемых чисел while ( a < b ) { while ( something_else() ) // проверка на наличие { // чего либо for ( i = 10; i >= 0; i-- ) { arr[i] = some_fun(i); // обработка массива } } 6

üКомментарий не должен подтверждать очевидное Примеры плохих комментариев /-----------------++x; // увеличить x на единицу /-----------------// обнуление массива for ( i = 0 ; i < n ; i ++ ) { arr[i] = 0; } 7

üКомментарии функций и процедур /*Получает индекс элемента массива с заданным значением * * value - значение элемента массива * Возвращает индекс элемента с заданным значением, либо -1, если элемент не найден*/ int the_function(int value) { for ( i = size; i >= 0; i-- ) { if (arr[i] == value) return i; } return -1; } üКомментарий не должен затруднять чтение программы 8

Именование переменных 9

üИмена должны быть обычными словами английского языка, описывающими то, что делает функция, аргумент или переменная Говорящие имена переменных result – результат выполнения функции size – размер массива temperature – значение температуры Попытка использования другого языка int Kolichestvo; int Koren; int Derevo; 10

üПользуйтесь длинными, содержательными именами для глобальных объектов и короткими — для локальных Объявление глобального имени int Count. Active. Docs =0; // количество активных документов Неоправданно длинные локальные имена for(Element. Index = 0 ; Element. Index < number. Of. Elements ; Element. Index++ ) { element. Array[Element. Index] = Elementlndex; } Правильные локальные имена for (i = 0; i < nelems; i++) { elem[i] = i; } 11

ü Различные стили именования переменных Стиль именования Кэмел Back. Color Last. Modified Date. Time Get. Type Set. Font. Value Стиль именования Паскаль back. Color last. Modified date. Time get. Type set. Font. Value 12

ü Пользуйтесь только общепринятыми сокращениями и аббревиатурами Аббревиатуры при именовании переменных col cur i j max min — — — индекс столбца; текущий; обобщенные счетчики циклов; максимум (обычно в качестве префикса или суффикса); минимум (обычно в качестве префикса или суффикса); ü Давайте функциям активные имена get. Time(); show. Value(); Пример плохого имени функции возвращающей логическое значение if (checkoctal(с)). . . Пример правильного имени функции возвращающей логическое значение if (is. Octal(с)). . . 13

ü Не используйте в качестве имен тарабарщину Например венгерскую нотацию LPCSTR lpszstr; То же самое const char *str; ü Не используйте в программе «магических» чисел. Присваивайте константам символические имена. Пример плохого кода for (i = 34 ; i < 67 ; i ++ ) { arr_[i] = 12; } Пример хорошего кода const int INIT_VAL = 12; const int SIZE_ARRAY = 67; . . . for (i = 0 ; i < SIZE_ARRAY ; i ++ ) { arr_[i] = INIT_VAL; } 14

Форматирование кода 15

üИспользуйте аккуратные столбцы везде, где можно Сравните данный кусок кода … int x; // Опишите, что делает x. unsigned long int (*pfi)(); // Опишите, что делает pfi. const char *the_variable; // Опишите, что делает the_variable. int z; // Опишите, что делает z. x = 10; // Здесь идет комментарий. the_variable = x; // Здесь второй комментарий. z = x; // A здесь третий. 16

üИспользуйте аккуратные столбцы везде, где можно С текущим куском кода … int x; unsigned long int ( *pfi )(); int z; const char *the_variable; x = 10; the_variable = x; z = x; // // // Опишите, что делает x. Опишите, что делает pfi. Опишите, что делает z. Опишите, что делает the_variable. // Здесь идет комментарий. // Здесь второй комментарий. // A здесь третий. 17

üРасполагайте в строке только один оператор üОтдельная функция должна помещаться на экране üМожно использовать штриховую линию для зрительного разделения функций //---------------------------int fun. ONE(int, float) { //something } //---------------------------int fun. TWO(char*, bool) { //something } 18

üРасполагайте большие комментарии, строки, вызовы подпрограмм и функций на нескольких строчках ///Пример: (плохой код) cout<<"Меня стоит расположить в несколько строчек, потому что Пример: (хороший код) cout<<"Меня стоит расположить в несколько строчек, " "потому что иначе тебе придется прокручивать каретку, " "чтоб просмотреть меня целиком"<

ü Стили расстановок скобок Стиль Алмена if( condition ) { code(); } else { more_code(); } Стиль Кернигена И Ричи if( condition ){ code(); } else { more_code(); } Стиль GNU Whitesmith if( condition ) { code(); } else { more_code(); } ü Используйте единообразный стиль на всем протяжении программы 20

üПробелы и абзацы — одни из наиболее эффективных комментариев //---------------------------int fun. ONE(int, float) { //первый логический //блок в функции //второй логический //блок в функции //третий логический //блок в функции } //--------------------------- 21

ü Разделять пробелами все операторы в выражениях вместо if(i<0) { … } следует писать if ( i < 0 ) { … } вместо for(i=0; i<100; i++) { … } следует писать for ( i = 0 ; i < 100 ; i++ ) { … } 22

ü Пробел или табуляция? ü Используйте отступы в два или четыре пробела(лучше четыре) Сравните данный вариант void f( void ) { if( x ) yyy(); more_code(); even_more_code(); } С текущим вариантом void f( void ) { if( x ) yyy(); more_code(); even_more_code(); } 23

Оператор условия if-else Общая форма оператора if следующая if ( выражение ) оператор; else оператор; Лестница if-else-if if ( else else выражение ) оператор; if ( выражение )оператор; if ( выражение )оператор; 24

ü Условные операторы выделяются абзацными отступами Плохой вариант if( by_land ) one() else two(); Хороший вариант if( by_land ) one(); else two(); Исключение if( by_land ) { one(); } else if( by_sea ) { two(); } else if( by_air ) { three(); } 25

Оператор выбора switch Общая форма оператора switch следующая switch(выражение) { case константа_1: оператор; break; case константа_2: оператор; break; case константа_3: оператор; break; ………………………………………… default: оператор; break; } 26

Пример switch(menu) { case file. Open: file. Open(); break; case file. Save: file. Save(); break; case Exit. Program: ; default: Exit. Program(); break; } 27

Функции üФункция должна делать только одно дело üФункция должна вызываться более одного раза, но… üКод, используемый более одного раза, должен быть помещен в функцию 28

Выражения и операторы 29

üЗаписывайте выражения в естественной форме Неправильно if (!(block_id < actblks) || !(block_id >= unblocks)) Правильно if ((block_id >= actblks) || (block_id < unblocks)) üИспользуйте скобки во избежание двусмысленности Менее читаемое выражение 1 еар_уеаг =у%4==0&&у% 100 != 0 || у % 400 == 0; Более читаемое выражение 1 еар_уеаг = ((у % 4 == 0) && (у % 100 1=0)) || (у % 400 == 0); 30

üВыражайтесь как можно понятнее üУчитывайте возможные побочные эффекты Менее очевидное выражение str[i++] = ' '; array[i++] = i; Более очевидноее выражение str[i++] = ' '; str[i++] = ' ; array[i] = i; i++; 31

Общие пожелания 32

ü Разбивайте сложные проблемы на задачи меньшего размера üИзменяя код прежде всего, не навреди üПустые потери времени üЧитайте чужой код 33

üИзбегайте дублирования усилий Неправильно if( strcmp(a, b) < 0 ) { } else if( strcmp(a, b) > 0 ) { } else if( strcmp(a, b) == 0 ) { } Правильно int cmp = strcmp(a, b); if( cmp < 0 ) { } else if( cmp > 0 ) { } else // остается случай cmp == 0 { } 34

üРассчитывайте на невозможное f( int i ) // переменная i должна иметь значение 1 или 2. { switch( i ) { case 1: сделать_нечто(); break; case 2: сделать_нечто_другое(); break; default: fprintf(stderr, "Внутренняя ошибка в f(): неверное значение i (%d)", i ); exit( -1 ); } } 35

üПомещайте код, динамически распределяющий и освобождающий память, в одном и том же месте void user( void { p = malloc( producer( p consumer( p free( p ); } ) size ); ); ); // пользователь // изготовитель // потребитель üРазбивайте сложные выражения на части Неочевидное выражение *х += (*xp=(2*k < (n-m) ? с[к+1] : d[k--])); Очевидное выражение if (2*k < n-m) *xр = c[k+1]; else *хр = d[k--]; *х += *хр; 36

37