uip-code-style.c

/* Это официальный стиль кодирования uIP. */

/**
 * \defgroup codestyle Стиль кодирования
 *
 * Здесь описано, как документируется модуль Doxygen - он начинаестя с \defgroup
 * ключевого слова Doxygen, которое размещается в начале файла, чтобы определить модуль,
 * и использует ключевое слово Doxygen \addtogroup для все других файлов, которые
 * принадлежат одному и тому же модулю. Обычно \defgroup размещается в заголовочном
 * файле с расширением .h, и \addtogroup размещается в файле с расширением .c.
 *
 * @{
 */

/**
 * \file
 *         Общее описание, что это за файл, и для чего нужен.
 * \author
 *         Adam Dunkels <adam@sics.se>
 *
 *         Каждый файл, который является частью документированного модуля, имеет в себе
 *         блок \file, иначе он не будет показан в секции "Модули" Doxygen.
 */

/* Одиночная строка комментария выглядит примерно как эта строка. */

/*
 * Многострочный коменнтарий должен быть оформлен как показано тут. Комментарии должны
 * предпочительно быть полными предложениями, заполненными так, чтобы быть похожими на
 * реальные параграфы.
 */

#include "uip.h"

/*
 * Убедитесь, что все не глобальные переменные помечены ключевым словом static.
 * Это уменьшает размер таблицы символов.
 */
static int flag;

/*
 * Все переменные и функции, которые видимы вне файла, должны предварительно
 * ожидать имя модуля, относящегося к ним. Так проще знать, где искать определения
 * для функций и переменных.
 *
 * Поместите разделители (одну строку комментария, состоящую только из тире)
 * между функциями.
 */
/*---------------------------------------------------------------------------*/
/**
 * \brief      Используйте для функций документацию Doxygen.
 * \param c    Кратко опишите все параметры.
 * \return     Кратко опишите возвращаемое значение.
 * \retval 0   Функции, которые возвращают несколько указанных значений,
 * \retval 1   могут использовать ключевое слово \retval вместо \return.
 *
 *             Поместите длинное описание того, что функция делает, после
 *             преамбулы из ключевых слов Doxygen.
 *
 *             Этот шаблон всегда должен использоваться для документирования
 *             функций. Текст после введения используется как документация
 *             для функции.
 *
 *             Прототипы функция должны иметь возвращаемый тип на одной строке,
 *             а имя функции и аргументы на другой (без пробела между именем
 *             и первой круглой скобкой), сопровождаемые одной круглой скобкой
 *             на той же строке.
 */
void
code_style_example_function(void)
{
  /*
   * Локальные переменные всегда должны быть определены в начале
   * тела функции.
   */
  int i;                   /* Используйте короткие имена для
                              счетчиков цикла. */

  /*
   * Не должно быть никаких пробелов между ключевыми словами и первой
   * круглой скобкой. Вокруг бинарных операторов должны быть пробелы,
   * но не должно быть никаких пробелов между унарным оператором
   * и его операндом.
   *
   * Фигурные скобки, которые идут за операторами for(), if(), do и case(),
   * должны находиться на той же строке, что и оператор.
   */
  for(i = 0; i < 10; ++i) {
    /*
     * Всегда используйте полный блок (фигурные скобки) после if(), for() и
     * while(), даже если они управляют только одной строкой кода.
     * Это упрощает чтение и модификации, и уменьшает вероятность
     * появления ошибки.
     */
    if(i == c) {
      return c;           /* Вокруг возвращаемых значений не должно быть круглых скобок. */
    } else {              /* Ключевое слово else размещается между фигурными скобками,
                              всегда на одной строке. */
      c++;
    }
  }
}
/*---------------------------------------------------------------------------*/
/*
 * Статические (не глобальные) функции не нуждаются в комментариях стиля Doxygen.
 * Имя не должно предварительно ожидаться с именем модуля - если сделать так,
 * то это создаст путаницу.
 */
static void
an_example_function(void)
{
  
}
/*---------------------------------------------------------------------------*/

/* Вот так должен заканчиваться \defgroup блок от начала файла: */

/** @} */