4.2. Имена
Основное требование к выбору имен (идентификаторов) – понятность. Имена переменных должны отражать их смысловую нагрузку. Использование сокращений разрешается, но следует избегать слишком коротких непонятных вариантов. Использование однобуквенных идентификаторов (i, j, k и т.д.) разрешено только в случаях, когда время жизни объекта обозримо, например, для переменной цикла.
Общее правило образования идентификаторов следующее: идентификатор состоит из отдельных слов, преимущественно английских (или понятных сокращений); в качестве разделителя слов используется символ подчеркивания '_', если используются все малые или все большие буквы, или слова разделяются первыми большими буквами. Запрещается использовать большие буквы, если первая буква идентификатора малая.
Слова в именах классов пишутся с большой буквы (в особых случаях допускается использовать все большие), в именах переменных, функций класса и локальных переменных – малыми, в именах констант – всеми большими. Глобальные и статические переменные пишутся всегда с большой буквы.
Пример плохого стиля:
int a,b,s;
char c[100];
char d[100];
char e[255];
int i, j;
Довольно трудно, не вдаваясь в программу, определить, что и для каких целей служит. Другое дело:
int slag1, slag2; // Слагаемые
int summa; // Сумма
char find_word[100]; // Слово для поиска
char replace_word[100]; // Слово для замены
char file_name[255]; // Имя файла
int i, j; // Счётчики циклов
Комментарием тут является уже само обозначение, смысл которого воспринимается сразу, так что приведенные комментарии почти не несут смысловой нагрузки; дополнительно следует отметить особое назначение переменной в алгоритме.
4.3. Комментарии
В начале каждого файла с первой позиции следует писать комментарий со следующей информацией:
-
название проекта;
-
фирма – разработчик;
-
научный руководитель проекта, телефон;
-
разработчик файла;
-
и отдельно, через пустую строку, функциональное назначение файла.
Пример:
/*
Проект: графический редактор проектирования топологии символьного уровня
Организация: Санкт-Петербургский государственный электротехнический университет "ЛЭТИ"
Научный руководитель к.т.н., доцент, с.н.с. Зуев Игорь Станиславович, тел. (+7)(812)(...)
Разработчик: А.Б.Максимов
Назначение: определение базового контейнерного класса TpObject объектов топологии
*/
Целесообразно комментировать каждый формальный параметр функции и объявленную переменную. Исключение может быть сделано только для тривиальных переменных, имеющих вспомогательный характер и ограниченное обозримое на одном экране место использования. Следует выделять комментариями большие логически законченные куски. Обязательно комментируются тонкие места алгоритма.
Пример плохого стиля:
printf(“Введите имя файла”); //Вывод надписи на экран
fflush(stdin); //Очистка буфера клавиатуры
scanf(“%s”, file_name); //Считывание имени файла
file=fopen(file_name, “rt”); //Использование функции fopen
if (file==NULL) //Если file==NULL,
printf(“Файл не открылся”); //то вывод надписи на экран
Вполне очевидно, что printf (…) служит для вывода на экран какой-либо информации. Но попробуйте определить, для каких целей служит весь блок.
Не следует дублировать комментариями то, что следует из семантики и синтаксиса языка программирования. Лучше этот фрагмент переписать так:
printf(“Введите имя файла”); //Считывание имени файла
fflush(stdin);
scanf(“%s”, file_name);
file = fopen(file_name, “rt”); //Открытие файла
if (file == NULL) //Проверка открытия файла
printf(“Файл не открылся”);
При написании комментариев следует, по возможности, пользоваться двойной косой чертой '//', а не скобками '/*' и ‘*/’: это облегчает тестовое выключение частей текста, например, при поиске ошибок в сложных случаях.
Комментарии, описывающие совершаемое действие лучше писать перед комментируемой частью с позиции, соответствующей данному уровню вложенности. Комментарии к переменным и членам класса лучше писать справа.
Перед началом определения класса должен стоять комментарий-разделительная строка и назначение класса. Например:
////////////////////////////////////////////////////////////
// Транзистор - элемент TRAN
class TpTransistor: public TpNamedElem1Smpl
{ //...
}