Program documentation rules

Правила оформления и документирования программы
для сдачи терминальных заданий
1. Каждая задача должна быть представлена отдельным проектом в Microsoft Visual
C++. Все необходимые нестандартные файлы/библиотеки должны присутствовать
в самом проекте. Имя проекта должно совпадать с номером задачи (использовать
символ «подчерк» вместо символа «тире», например: 2_1). Название файла,
содержащего функцию main() должно быть созвучно названию задачи, например
NOD, squares, different_elements.
2. При выдаче результатов на экран или при запросе каких-либо данных программа
должна сопровождать результаты/запрос сопроводительными надписями
(например «Input number:»), если это не оговорено явно в задании. Если программа
требует ввода дополнительных параметров с командной строки, то список
доступных параметров должен выдаваться самой программой на специальный
запрос. Принцип прост: интерфейс программы должен быть интуитивно понятен и
удобен в использовании.
3. Любая строка должна полностью находится в поле зрения при просмотре файла в
стандартном редакторе Visual Studio C++. Т.е., чтобы не требовалось пользоваться
горизонтальной прокруткой. Длинные строки следует дробить на более короткие
(смотри возможные варианты разделения строк в примере).
4. Обязательные комментарии в тексте программы (для каждого файла):
a. Самыми первыми строками должен идти комментарий, содержащий общую
информацию о файле: имя файла, краткое описание, автора, дату создания.
b. Если подключаются какие-то нестандартные заголовки, то должен
присутствовать комментарий, объясняющий, что это за заголовок и зачем он
подключается.
c. Каждая глобальная переменная должна содержать комментарий,
описывающий ее назначение.
d. Каждая функция должна содержать комментарий описывающий:
i. Назначение функции
ii. Входные параметры
iii. Выходные параметры
e. Если программа может использовать какие-либо аргументы командной
строки, то они должны быть перечислены в комментариях к функции main()
f. Объявление переменной внутри функции должны содержать комментарий,
если назначение переменной непонятно из ее названия. Для счетчиков
(переменных, хранящих номер итерации цикла в операторах for(), while())
предпочтительно использовать переменные с именами i, j, k, l, m.
5. Форматирование:
a. Секция объявления переменных должна отделятся от основного тела
функции
b. Текст, находящийся на одном уровне вложенности должен иметь
одинаковый отступ от начала строки. Каждый новый уровень вложенности
увеличивает отступ на константное значение. Каждый составной оператор
(блок { ... }) увеличивает уровень вложенности на 1.
c. При использовании константы в сравнениях с операторами != и ==
предпочтительно константу писать слева оператора. Это позволяет избежать
часто распространенной ошибки, когда вместо != или == пишется =.
d. При использовании операторов if, while, for предпочтительно всегда
заключать тело цикла в скобки {}, даже если в теле цикла находится только
один оператор.
Пример корректно оформленной программы
/*
*
*
*
*
*
*
*/
sample.c
This sample program shows documentaton rules.
Author: den, 25/09/2001
Modified:
den, 26/09/2001 Added some new types of comments
#include <stdio.h>
#include "docs.h"
//header contain constants documentation rules
#define DIM 6 //Default dimension of vector
int test1[DIM] = {1, 2, 3, 4, 5, 6};
int test2[DIM] = {1, 4, 5, 10, 0, 2};
//test array #1
//test array #2
/* Long initialization string as example */
int test3[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9,
1, 2, 3, 4, 5, 6, 7, 8, 9,
1, 2, 3, 4, 5, 6, 7, 8, 9,
1, 2, 3, 4, 5, 6, 7, 8, 9 };
/* Another long initialization string as example.
* Use symbol \ in long string dividing.
*/
char* hello="Hi! This program will help you to understand \
basic documentation rules.";
int mod = 2; //Step for element printing
/*
Function does nothing.
*
*
parameters: none
*
return:
none
*/
void example(void) {
}
/*
Function calculates the sum of two arguments.
*
*
parameters:
*
a - first argument of sum
*
b - second argument of sum
*
return: sum of two arguments
*/
int sum (int a, int b) {
return a+b;
}
/* Calculate a number of the same elements in 2 arrays.
* Each array contains elements of type “int”
*
* parameters:
*
a – the first array
*
b – the second array
*
dim - array dimension
* result: a number of the same elements in 2 arrays
*/
int sameElements (int a[], int b[], int dim) {
int
num=0;
int i,j; //counters
for (i=0; i<dim; i++) {
for (j=0; j<dim; j++) {
if (a[i] == b[j]) {
num++;
}
}
}
return num;
}
/* Main function prints number of the same elements in two arrays;
* shows second array elements with step that defined in special global
* variable (mod).
*/
void main() {
int i;
// Function call is very long. It is broken into 2 lines.
printf ("Number of the same elements: %d\n\n",
sameElements(test1, test2, DIM));
for (i=0; i<DIM; i++) {
//constant is first because it helps to detect possible error
if (0 != i%mod) {
printf("test2[%d]=%d\n",i,test2[i]);
}
}
}