Приложение г. Требования к оформлению программ на языке Си г.1 Соглашения по идентификаторам
Г.1.1 Подбор идентификаторов
А. Все идентификаторы должны выбираться из соображений читаемости и максимальной семантической нагрузки. Например:
const float Eps = 0.0001; // точность
unsigned short Sum; // сумма
unsigned char Message[ 20 ]; // сообщение
Неудачными можно считать идентификаторы:
const float UU = 0.0001; // точность unsigned short Kk; // сумма unsigned char Zz[ 20 ]; // сообщение
Б. Идентификаторы рекомендуется подбирать из слов английского языка. Например:
// выдает звуковой сигнал заданной частоты и длительности void Beep( unsigned short Hertz, unsigned short MSec ); // выдает True (1), если файл с именем FName существует unsigned char ExistFile( unsigned char* FName ); // признак окончания работы с программой unsigned char Done;
// размеры изделия (ширина, высота) unsigned short Width, Height;
Не очень удачными можно считать идентификаторы:
// выдает звуковой сигнал заданной частоты и длительности void Zvuk(unsigned short Chast, unsigned short Dlit ); // выдает True (1), если файл с именем Im существует unsigned char EstFile(unsigned char* Im ); // признак окончания работы с программой unsigned char Konec;
// размеры изделия (ширина, высота) unsigned short Shirina, Vysota;
Г.1.2 Написание идентификаторов
Существует два основных способа написания идентификаторов.
А. В любых идентификаторах каждое слово, входящее в идентификатор, писать, начиная с большой буквы, остальные буквы – маленькие.
Например:
-
float NextX, LastX;
// следующая и предыдущая итерация
char BeepOnError;
// подавать ли звуковой сигнал при
// неправильном вводе пользователя?
unsigned char FileName[ 20 ];
// стандартная функция модуля Graph; выдает описание
// ошибки использования графики по ее коду unsigned char* GraphErrorMsg( short ErrCode );
Б. В любых идентификаторах каждое слово, входящее в идентификатор, разделять символом ―_‖, при этом все буквы – маленькие.
Например:
-
float next_x, last_x;
// следующая и предыдущая итерация
char beep_on_error;
// подавать ли звуковой сигнал при
// неправильном вводе пользователя?
unsigned char file_name[ 20 ];
// стандартная функция модуля Graph; выдает описание
// ошибки использования графики по ее коду unsigned char* graph_error_msg( short err_code );
Г.2 Соглашения по самодокументируемости программ
Г.2.1 Комментарии
А. Комментарии в теле программы следует писать на русском языке и по существу так, чтобы программист, не участвовавший в разработке программы (но имеющий опыт работы на языке Си), мог без особого труда разобраться в логике программы, и, при необходимости, сопровождать данный программный продукт.
Б. Рекомендуется комментарии к программе писать после символов //, а /* и */ использовать при отладке программы как "заглушки" участков программного кода.
Г.2.2 Спецификация функций Для каждой пользовательской функции должна быть описана в виде комментария спецификация, содержащая следующую информацию [95]:
Назначение функции;
Описание семантики параметров-значений (параметров, передаваемых по значению).
Описание семантики параметров-переменных (параметров, передаваемых по ссылке).
Описание семантики возвращаемого значения.
Например:
/////////////////////////Gauss////////////////////////////// // Решение системы линейных алгебраических уравнений
// методом Гаусса.
// Вход:
// A - матрица коэффициентов системы; // B - столбец свободных членов системы; // Eps - точность вычислений.
// Выход:
// X - вектор решения;
// HasSolution - флаг, устанавливаемый в True, если
-
//
решение системы существует, и в False
//
во всех остальных случаях;
//
NumOfRoots
- число корней в решении системы, может
//
принимать значения:
//
0 - если решение системы не
//
существует,
//
MaxN - если решение системы
//
существует и единственно,
//
MaxInt - если существует бесконечное
//
множество решений;
//
Det
- значение определителя матрицы A;
//
AForReverse
- нижняя треугольная матрица,
//
полученная из A в результате
//
выполнения прямого хода алгоритма
//
Гаусса;
//
BForReverse
- столбец свободных членов, полученный
//
из B в результате выполнения
//
прямого хода алгоритма Гаусса.
// Результат: 0 - успешно,1 – ошибка.
//////////////////////////////////////////////////////////////
unsigned char Gauss( Matrix A, Vector B, float Eps, Vector* X, char* HasSolution, short* NumOfRoots, float* Det, Matrix* AForReverse,
Vector* BForReverse )
{ … return 0; … return 1;
}
Замечание:
Если функция реализует какой-либо вычислительный метод (например: нахождение площади фигуры методом трапеций, поиск минимума функции методом Ньютона и т.п.), рекомендуется в теле функции поместить комментарий с кратким описанием метода, либо ссылку на источник, где описан метод [95].
Г.2.3 Спецификация программного файла или модуля
Программный
файл или модуль должен начинаться со
спецификации в виде комментария,
содержащего следующую информацию [95]:
Идентификация проекта, к которому
принадлежит файл.
Назначение (название) и имя файла.
Версия файла.
Фамилия автора.
Описание модуля.
История изменений модуля.
Например:
/*--------------------------------------------------------------
Проект: ABC-1.0
Название: Математические расчеты
Файл: primes.c
Версия: 1.0.2
Автор: Иванов И.И.
Описание: Подсчет количества простых чисел.
Изменения:
----------------------------------------------------------------
N Дата Версия Автор Описание
---------------------------------------------------------------- 1 01.03.07 1.0.1 Иванов И.И. Расчет в промежутке [1..200].
2 05.07.07 1.0.2 Иванов И.И. Расчет в заданном пользователем промежутке.
--------------------------------------------------------------*/
Замечание:
После спецификации программного файла рекомендуется поместить комментарий с указаниями по запуску программы и работе с ней (указаниями по использованию модуля другими программистами) или ссылку на источник, который использован при составлении программы (модуля).