Комментарии

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

// 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 есть специальное окно, в котором отображаются все подобные метки.


Изменено: