注释的反面教材

都说好注释应该写Why而不是How，这里给个只写How的废话注释作为反面教材。

http://blog.csdn.net/zoomdy/article/details/71698683
mingdu.zheng at gmail dot com

void SpiritRadioSetModulation(ModulationSelect xModulation){  uint8_t tempRegValue;  /* Check the parameters */  s_assert_param(IS_MODULATION_SELECTED(xModulation));  /* Reads the modulation register */  SpiritSpiReadRegisters(MOD0_BASE, 1, &tempRegValue);  /* Mask the other fields and set the modulation type */  tempRegValue &=0x8F;  tempRegValue |= xModulation;  /* Writes the modulation register */  g_xStatus = SpiritSpiWriteRegisters(MOD0_BASE, 1, &tempRegValue);}

上面这段代码里的注释是不是都是废话呢。典型的为了写注释而写注释，代码本身的可读性已经非常强了，看代码本省就足够理解代码了，何必再写多余的注释？4行注释都是How型注释。所谓How型注释是解释代码是怎么工作的，Why型注释是解释代码为什么要这么写。How型的注释是完全没有必要的。可读性强的代码，阅读代码本省就可以理解代码是怎么工作的，写注释去解释可读性差的代码还不如想想怎么改进代码的可读性呢。优秀的代码应该是自注释的（Self-Documenting Code），就是说代码自己能把自己解释清楚，不用注释来瞎搀和。

• 《避免代码注释的五大理由》
• 《五种应该避免的代码注释》