Книга: Разработка ядра Linux

Комментарии

Комментарии

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

В ядре используются комментарии в стиле С, хотя компилятор 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.

Оглавление книги