[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Программирование, языки" / Оглавление документа

9. Комментарии

Каждая программа должна начинаться с комментария, кратко говорящего, для чего она предназначена. Например: 'fmt - filter for simple filling of text'.

Пожалуйста, помещайте комментарий для каждой функции, говорящий, что эта функция делает, какие аргументы получает, какие значения аргументов допустимы и для чего она используется. Не нужно дублировать словами значение описания аргументов, если типы используются обычным образом. Если имеется что-либо нестандартное в использовании аргументов (например, аргумент типа char * указывает на адрес второго символа строки, а не первого), или не каждое возможное значение может быть передано как аргумент (например, строка, содержащая символ перехода на новую строку, может быть обработана неправильно), это надо обязательно оговорить.

Объясните также смысл возвращаемого значения, если оно есть.

Необходимо помещать два пробела в конце предложения в Вашем комментарии, для того, чтобы правильно функционировали команды Emacs, работающие с предложениями. Пишите предложение целиком, первое слово в предложении должно начинаться с большой буквы (если это слово не является идентификатором, начинающимся с маленькой буквы: изменение написания делает его другим идентификатором). Если Вы не хотите начинать предложение с маленькой буквы, перепишите предложение другим образом (например, 'The identifier lower-case is ...').

Комментарий к функции будет намного яснее, если Вы используете мнемоничные имена аргументов, которые говорят что-то об их значениях. Имя аргумента само по себе должно быть написано маленькими буквами, большие же буквы следует использовать, когда Вы говорите о значении, а не о самой переменной. Следует писать "the inode number NODE_NUM" вместо "an inode".

Обычно не нужно повторять имя функции в комментарии, предшествующему ей, потому что читатель может увидеть его и так. Исключением является случай, когда комментарий настолько длинный, что описание функции не помещается с ним на одном экране.

Следует писать комментарий для каждой static-переменной, например:

/* Nonzero means truncate lines in the display;   
    zero means continue them. */   
 int truncate_lines;   

#ifdef foo   
    ...   
 #else /* not foo */   
    ...   
 #endif /* not foo */   

#ifndef foo   
    ...   
 #else /* foo */   
    ...   
 #endif /* foo */   

Партнёры:

Хостинг: