Комментарии

Комментарии

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

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

Поделитесь на страничке

Следующая глава >

Похожие главы из других книг

1.2 Комментарии

Из книги C++ автора Хилл Мюррей

1.2 Комментарии Часто бывает полезно вставлять в программу текст, который предназначается в качестве комментария только для читающего программу человека и игнорируется компилятором в программе. В С++ это можно сделать одним из двух способов.Символы /* начинают


2.1 Комментарии

Из книги Давайте создадим компилятор! автора Креншоу Джек

2.1 Комментарии Символы /* задают начало комментария, заканчивающегося символами */. Комментарии не могут быть вложенными. Символы / / начинают комментарий, который заканчивается в конце строки, на которой они


Комментарии

Из книги Примеры использования Паттерн Singleton (Одиночка) автора Федоров Дмитрий

Комментарии Вплоть до этого времени я тщательно избегал темы комментариев. Вы могли бы подумать, что это будет простая тема... в конце концов компилятор совсем не должен иметь дела с комментариями; он просто должен игнорировать их. Чтож, иногда это так.Насколько простыми


Комментарии: 

Из книги Обработка событий в С++ автора Клюев Александр

Комментарии:  Как бы так это заделать??? Во первых, статья очень хорошая и полезная, спасибо. Применил в реальной программе я этот сингелтон и остался очень доволен. Но мне надо было несколько изменить поведение исходного класса. У меня ситуация такая: есть клиент, который


Комментарии:  

Из книги Симуляция частичной специализации автора Кузнецов Павел

Комментарии:   Не всегда корректный код Вы приводите указатель на функцию-член класса клиента к указателю на функцию из конкрентного класса (slot::Thunk), это для некоторых классов может быть невозможно, ошибка компилятора, что-то типа "указатели имеют разную природу",


Комментарии:

Из книги Делегаты на C++ автора Шаргин Александр

Комментарии: template‹class TRet, class TP1› class CDelegate1 {  //… }; template‹class TP1› class CDelegate1‹bool, TP1› {  //… }; template‹class TRet, class TP1, class TP2› class CDelegate2 {  //… }; template‹class TP1, class TP2› class CDelegate2‹bool, TP1, TP2› { //… }; и т.д… Андрей 20.3.2003 12:22 ... и статической T не надо А мне как то больше понравился такой


Комментарии:

Из книги Программирование автора Козлова Ирина Сергеевна

Комментарии: наследование операторов ›Дело в том, что в языке C++ операторы не наследуются. Это не верно по крайней мере для MSVC++. Более того этот метод используется при написании функтора из библиотеки Loki http://fara.cs.uni-potsdam.de/~kaufmann/?page=lokiport (файл Functor.h), см. также


21. Комментарии в СИ++

Из книги Справочное руководство по C++ автора Страустрап Бьярн

21. Комментарии в СИ++ Часто бывает необходимо вставлять в программу текст, который используется в качестве комментария только для читающего программу человека и не учитывается компилятором в программе. В C++ это возможно осуществить одним из двух способов. Символы /*


R.2.2 Комментарии

Из книги Delphi. Учимся на примерах автора Парижский Сергей Михайлович

R.2.2 Комментарии Символы /* начинают комментарий, который завершается символами */. Такие комментарии не могут быть вложенными. Символы // начинают комментарий, который завершается концом этой строки. Символы //, /* и */ не имеют специального назначения в комментарии // и


Комментарии

Из книги Исчерпывающее руководство по написанию всплывающих подсказок автора Джек Роджер

Комментарии Комментарии — это фрагменты исходного текста программы, которые не компилируются и служат для пояснения кода. Для обозначения комментариев в программах на языке Object Pascal используют следующие конструкции:• // — комментарии в одной строке;• { } или (* *) —


Комментарии: 

Из книги HTML 5, CSS 3 и Web 2.0. Разработка современных Web-сайтов. автора Дронов Владимир

Комментарии:  Небольшое добавление Искал способ попроще включить поддержку ToolTips без явного использования класса CToolTipCtrl. И в результате сам сделал следующее: int CContentWnd::OnToolHitTest(CPoint point, TOOLINFO* pTI) const {  int nHit=0;  CString csText;  csText="Закрыть окно";  HWND m_hWnd=this->GetSafeHwnd();  pTI->hwnd =


Комментарии

Из книги Язык программирования Си для персонального компьютера автора Бочков C. О.

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


Комментарии CSS

Из книги Фундаментальные алгоритмы и структуры данных в Delphi автора Бакнелл Джулиан М.

Комментарии CSS В главе 2 мы узнали о комментариях — особых фрагментах HTML-кода, которые не обрабатываются Web-обозревателем и служат для того, чтобы Web-дизайнер смог оставить какие-то заметки для себя или своих коллег. Для этого язык HTML предоставляет специальный


Комментарии

Из книги Краткое введение в программирование на Bash автора Родригес Гарольд

Комментарии Комментарий — это последовательность символов, которая воспринимается компилятором языка Си как отдельный пробельный символ и игнорируется. Комментарий имеет следующий вид:/* <символы> */<символы> должны принадлежать множеству представимых символов.


Комментарии

Из книги автора

Комментарии Это правило выглядит достаточно просто:----Правило № 3. Помещайте в код комментарии. Объясняйте ваши допущения (более того, проверяйте их с помощью утверждений). Описывайте сложные блоки кода. При изменении кода изменяйте и соответствующие комментарии. Не


Комментарии

Из книги автора

Комментарии Комментарии помогают сделать ваш код более читабельным. Они не влияют на то, что выводит программа. Они написаны специально для того, чтобы вы их прочли. Все комментарии в Bash начинаются с хэш-символа #, за исключением первой строки (#!/bin/bash), имеющей специальное