Здравствуйте, gress, Вы писали:

G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Собственно код, без комментариев, должен 100% давать ответ на вопрос "что здесь делается". Если из структуры кода это не понятно, то его надо рефакторить.
Комментарии должны отвечать на вопрос "зачем это делается" и "на что обратить внимание, меняя это код в будущем" там, где это критично.

Чтобы не быть голословным, пример плохого комментария:

void foo(Context context)
{
   DoSomething();

   // Set device registers
   set_register(REG_A, context.A);
   set_register(REG_B, context.B);
   set_register(REG_C, context.C | POWER_ON);

   DoSomethingElse();
}

Комментарий "Set device registers" бесполезен. Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод, благо оптимизатор, если надо, заинлайнит это с нулевым оверхедом:

inline void SetDeviceRegisters(Context context)
{
   set_register(REG_A, context.A);
   set_register(REG_B, context.B);
   set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
}

void foo(Context context)
{
   DoSomething();
   SetDeviceRegisters(context);
   DoSomethingElse();
}

С другой стороны, вот пример хорошего комментария:

inline void SetDeviceRegisters(Context context)
{
   set_register(REG_A, context.A);
   set_register(REG_B, context.B);

   //Clearing PERIPHERAL_BUS_ENABLED would prevent the device from responding
   //to subsequent commands until the user physically resets it.
   //See section 6.66 on page 420 in datasheet revision 13.
   //Hence, we always keep this bit on as a precaution.

   //WARNING: this bit is hardware-specific and should be updated when porting
   //to different hardware.
   set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
}

Здравствуйте, gress, Вы писали:

G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Собственно код, без комментариев, должен 100% давать ответ на вопрос "что здесь делается". Если из структуры кода это не понятно, то его надо рефакторить.
Комментарии должны отвечать на вопрос "зачем это делается" и "на что обратить внимание, меняя это код в будущем" там, где это критично.

Чтобы не быть голословным, пример плохого комментария:

void foo(Context context)
{
   DoSomething();

   // Set device registers
   set_register(REG_A, context.A);
   set_register(REG_B, context.B);
   set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);

   DoSomethingElse();
}

Комментарий "Set device registers" бесполезен. Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод, благо оптимизатор, если надо, заинлайнит это с нулевым оверхедом:

inline void SetDeviceRegisters(Context context)
{
   set_register(REG_A, context.A);
   set_register(REG_B, context.B);
   set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
}

void foo(Context context)
{
   DoSomething();
   SetDeviceRegisters(context);
   DoSomethingElse();
}

С другой стороны, вот пример хорошего комментария:

inline void SetDeviceRegisters(Context context)
{
   set_register(REG_A, context.A);
   set_register(REG_B, context.B);

   //Clearing PERIPHERAL_BUS_ENABLED would prevent the device from responding
   //to subsequent commands until the user physically resets it.
   //See section 6.66 on page 420 in datasheet revision 13.
   //Hence, we always keep this bit on as a precaution.

   //WARNING: this bit is hardware-specific and should be updated when porting
   //to different hardware.
   set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
}