Комментарии
С одной стороны, хорошему коду комментарии не нужны, он и так хорошо читается. С другой стороны, в больших проектах необходимо документировать код. В языке Си есть два вида комментариев: однострочные и многострочные.
// 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 есть специальное окно, в котором отображаются все подобные метки.