Как-то раз сидел в аудитории с ноутом около розетки, а в это время на соседней парте принимался зачет по программированию. Я не сильно вникал в суть вопросов на которые общались студент и преподаватель, назовем его Иван Ивановичем. Разговор был довольно спокойный и тихий, но у меня получилось выхватить часть. Преподаватель говорил о комментариях (видимо сдавалась программа, в которой не было ни строчки комментариев). Меня этот момент заинтересовал и я начал прислушиваться. Было замечено, что мне тоже интересно, преподаватель начал импровизированную лекцию. Ниже представлен тот небольшой кусок знаний который я тогда вынес с этой 5ти минутной лекции.

Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 2 и более программиста) и студентам будет полезно. Кроме того, все изложенные ниже советы имеют альтернативу и могут быть использованы лишь частично.

Почему я приписал сюда студентов? Они же, казалось бы, одни работают над программой на зачет! Препод, когда принимает программу, справедливо считается вторым разработчиком, который в идеале без помощи студента должен понять, что там написано и как оно работает.

Как писать код сразу с комментариями


По сути говоря, на той лекции принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:
int main()
{
     // Принять от пользователя два числа
     // Завести переменную для результата сложения
     // Вернуть результат сложения

     return 0;
}

И лишь когда готов каркас из комментариев, следует писать код который будет реализовывать то, что описано комментариями.
...
int main()
{
     double a,b;
     // Принять от пользователя два числа
     cin>>a;
     cin>>b;
     //Завести переменную для результата сложения
     double sum = a+b;
     // Вернуть результат сложения
     cout<<sum;

     return 0;
}

Как упоминалось выше, данный принцип представляет собой модифицированный принцип, хорошо зарекомендовавшего себя TDD. Тут следует понимать, что отступление от комментариев, в отличии от отступления от логики тестов, не приведет к тяжелым последствиям, ну разве что придется комментарии переписывать

Теперь представим «чисто гипотетическую» ситуацию, когда уже имеется код в 200 000 строк, написанный гениальным программистом криворуким индусом и не содержит ни строчки комментария. Однако вам необходимо, мало того что убить этого программиста понять этот код, но и сопровождать его в дальнейшем. Вы даже разобрались в этом коде, и будучи приличным человеком, решили дополнить код комментариями для, так сказать, будущих поколений. Но возникает вопрос: как?

Как комментировать уже существующий код


Ответ на этот вопрос довольно прост: комментируем сущности от родителя к потомку: класс -> метод -> код внутри метода (если необходимо).

Вполне логично будет задуматься: а что не нужно комментировать. Комментировать не надо в двух случаях (один из них поясняет почему пример кода выше был сильно утрированный):
  • Совсем уж очевидные вещи. Комментарии вида // инициализируем счетчик бесят больше чем их отсутствие
  • Непонятный код дополнять комментарием типа // ничего не понял

Относительно второго пункта стоит немного пояснить и привести пример: вставка 100 строк ассемблера код на C! Вы на нее смотрите и пишите комментарий // Многа букаф! Ниасилил
После этого человек пришедший после вашего увольнения на ваше место видит этот комментарий и… все! Он даже не будет пытаться в нем разобраться и эта ваша запись будет клеймом на этом куске кода до тех пор пока его не уберут (либо код, либо комментарий).

Напоследок

В заключение могу сказать, что искусство написания комментариев является неотъемлемой частью искусства программирования, поэтому комментарии писать надо, и, как бы пафосно это не звучало, но написанию качественных комментариев надо учиться.