Комментарии

С одной стороны, хорошему коду комментарии не нужны, он и так хорошо читается. С другой стороны, в больших проектах необходимо документировать код. В языке Си есть два вида комментариев: однострочные и многострочные.

// single line comment
/* multiline
comment */
/* of course, multiline comments can be made into single-line */

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

#if !defined (STM32F10X_LD) && !defined (STM32F10X_LD_VL) && !defined (STM32F10X_MD) && !defined (STM32F10X_MD_VL) && !defined (STM32F10X_HD) && !defined (STM32F10X_HD_VL) && !defined (STM32F10X_XL) && !defined (STM32F10X_CL) 
/* #define STM32F10X_LD */     /*!< STM32F10X_LD: STM32 Low density devices */
/* #define STM32F10X_LD_VL */  /*!< STM32F10X_LD_VL: STM32 Low density Value Line devices */
#define STM32F10X_MD     /*!< STM32F10X_MD: STM32 Medium density devices */
/* #define STM32F10X_MD_VL */  /*!< STM32F10X_MD_VL: STM32 Medium density Value Line devices */
/* #define STM32F10X_HD */     /*!< STM32F10X_HD: STM32 High density devices */
/* #define STM32F10X_HD_VL */  /*!< STM32F10X_HD_VL: STM32 High density value line devices */  
/* #define STM32F10X_XL */     /*!< STM32F10X_XL: STM32 XL-density devices */
/* #define STM32F10X_CL */     /*!< STM32F10X_CL: STM32 Connectivity line devices */
#endif

Раскомментировав макрос, мы подскажем препроцессору, например, номера прерываний, которые соответствуют данному МК.

#ifdef STM32F10X_MD
    /*!< ADC1 and ADC2 global Interrupt                       */
    ADC1_2_IRQn                 = 18,
    /*!< USB Device High Priority or CAN1 TX Interrupts       */
    USB_HP_CAN1_TX_IRQn         = 19,
    /*!< USB Device Low Priority or CAN1 RX0 Interrupts       */
    USB_LP_CAN1_RX0_IRQn        = 20,
    /*!< CAN1 RX1 Interrupt                                   */
    CAN1_RX1_IRQn               = 21,
    // ... 

Кроме того, комментарии часто используют, чтобы автоматически генерировать документацию. Для проектов, написанных на языках Си и C++, стандартом является кроссплатформенная система Doxygen, которая поддерживает форматы HTML, RTF, man, XML и даже LaTeX. Пример комментария-документации выглядит так:

/**
* @brief  Returns the last ADC converted data.
* @param  ADCx where x can be 1 to select the specified ADC peripheral.
* @retval The Data conversion value.
*/
uint16_t ADC_GetConversionValue(ADC_TypeDef* ADCx) {
    //...
}

Если вы работаете в среде Eclipse (или производных от нее, как CoIDE), то для организации процесса переписывания плохих участков кода (то есть тех, в которых была обнаружена ошибка или возможно использовать лучший алгоритм для решения задачи) стоит использовать слова-теги.

// TODO: make this function faster
void sort_clients(CLIENT_t* list, uint8_t n) {
    // code
}
// ...
// FIXME: if b == 0 => HardFault
uint8_t calculation(uint8_t a, uint8_t b) {
    // code
    return result;
}

В среде Eclipse есть специальное окно, в котором отображаются все подобные метки.


Изменено:

Язык Си: 3 комментария

  1. >Вместо нуля может быть почти любой другой символ. Плюс и минус работают по-другому. Для выравнивания числа по по левому краю, а не по правому, перед числом нужно поставить знак минус.
    Лишне по

  2. Термин «регистр ядра» довольно специфичен. Звучит не привычно. А почему не использовать термин CPU или процессор или на худой конец микроконтроллер?

  3. Смысл статических переменных вне функции мне кажется не раскрыт. Такой модификатор делает переменную недоступной из других единиц трансляции. Т.е. не будет конфликта имен между разными .с файлами.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Этот сайт использует Akismet для борьбы со спамом. Узнайте, как обрабатываются ваши данные комментариев.