Разработка ядра Linux - [189]

это делается. То, как реализован алгоритм, описывать не нужно, это должно быть ясно из кода. Если так сделать не получается, то, возможно, стоит пересмотреть то, что вы написали. Кроме того, комментарии не должны включать информацию о том, кто написал функцию, когда это было сделано, время модификации и др. Такую информацию логично размещать в самом начале файла исходного кода.

В ядре используются комментарии в стиле С, хотя компилятор gcc поддерживает также и комментарии в стиле C++. Обычно комментарии кода ядра должны быть похожи на следующие (только на английском языке, конечно).

/*
* get_ship_speed() - возвращает текущее значение скорости
* пиратского корабля
* Необходима для вычисления координат корабля.
* Может переходить в состояние ожидания,
* нельзя вызывать при удерживаемой блокировке.
*/

Комментарии внутри функций встречаются редко, и их нужно использовать только в специальных ситуациях, таких как документирование дефектов, или для важных замечаний. Важные замечания часто начинаются со строки "XXX: ", а информация о дефектах — со строки "FIXME: ", как в следующем примере.

/*
* FIXME: Считается, что dog == cat.
* В будущем это может быть не так
*/

У ядра есть возможность автоматической генерации документации. Она основана на GNOME-doc, но немного модифицирована и называется Kernel-doc. Для создания документации в формате HTML необходимо выполнить следующую команду.

make htmldocs

Для генерации документации в формате postscript команда должна быть следующей.

make psdocs

Документировать код можно путем введения комментариев в специальном формате.

/**
* find_treasure - нахождение сокровищ, помеченных на карте крестом
* @map - карта сокровищ
* @time - момент времени, когда были зарыты сокровища
*
* Должна вызываться при удерживаемой блокировке pirate_ship_lock.
*/
void find_treasure(int dog, int cat)
{
       /* ... */
}

Для более подробной информации см. файл Documentation/kernel-doc-nano-HOWTO.txt.

Использование директивы >typedef

Разработчики ядра не любят определять новые типы с помощью оператора typedef, и причины этого довольно трудно объяснить. Разумное объяснение может быть следующим.

• Определение нового типа через оператор typedef скрывает истинный вид структур данных.

• Поскольку новый тип получается скрытым, то код более подвержен таким нехорошим вещам, как передача структуры данных в функцию по значению, через стек.

• Использование оператора typedef — признак лени.

Чтобы избежать насмешек, лучше не использовать оператор typedef.

Конечно, существуют ситуации, в которых полезно использовать оператор typedef: сокрытие специфичных для аппаратной платформы деталей реализации или обеспечение совместимости при изменении типа. Нужно хорошо подумать, действительно ли оператор typedef необходим или он используется только для того, чтобы уменьшить количество символов при наборе кода.

Использование того, что уже есть

Не нужно изобретать паровоз. Ядро предоставляет функции работы со строками, подпрограммы для сжатия и декомпрессии данных и интерфейс работы со связанными списками — их необходимо использовать.

Не нужно инкапсулировать стандартные интерфейсы в другие реализации обобщенных интерфейсов. Часто приходится сталкиваться с кодом, который переносится с других операционных систем в систему Linux, при этом на основе существующих интерфейсов реализуется некоторая громоздкая функция, которая служит для связи нового кода с существующим. Такое не нравится никому, поэтому необходимо непосредственно использовать предоставляемые интерфейсы.

Никаких директив >ifdef в исходном коде

Использование директив препроцессора ifdef в исходном коде категорически не рекомендуется. Никогда не следует делать чего-нибудь вроде следующего.

 ...
#ifdef CONFIG_FOO
 foo();
#endif
 ...

Вместо этого, если макрос CONFIG_FOO не определен, необходимо определять функцию foo(), как ту, которая ничего не делает.

#ifdef CONFIG_FOO
static int foo(void)
{
 /* ... */
}
#else
static inline int foo(void) { }
#endif

После этого можно вызывать функцию foo() без всяких условий. Пусть компилятор поработает за вас.

Инициализация структур

Структуры необходимо инициализировать, используя метки полей. Это позволяет предотвратить некорректную инициализацию при изменении структур. Это также позволяет выполнять инициализацию не всех полей. К сожалению, в стандарте C99 принят довольно "страшненький" формат меток полей, а в компиляторе gcc ранее использовавшийся формат меток полей в стиле GNU признан устаревшим. Следовательно, для кода ядра необходимо использовать новый формат, согласно стандарту C99, каким бы ужасным он ни был.

struct foo my_foo = {
 .a = INITIAL_A,
 .b = INITIAL_B,
};

где а и b — это поля структуры struct foo, а параметры INITIAL_A и INITIAL_B — соответственно, их начальные значения. Если поле не указано при инициализации, то оно устанавливается в свое начальное значение, согласно стандарту ANSI С (указателям присваивается значение NULL, целочисленным полям — нулевое значение, а полям с плавающей точкой— значение 0.0). Например, если структура struct foo также имеет поле int с, то это поле в предыдущем примере будет инициализировано в значение 0.