Как-то раз сидел в аудитории с ноутом около розетки, а в это время на соседней парте принимался зачет по программированию. Я не сильно вникал в суть вопросов на которые общались студент и преподаватель, назовем его Иван Ивановичем. Разговор был довольно спокойный и тихий, но у меня получилось выхватить часть. Преподаватель говорил о комментариях (видимо сдавалась программа, в которой не было ни строчки комментариев). Меня этот момент заинтересовал и я начал прислушиваться. Было замечено, что мне тоже интересно, преподаватель начал импровизированную лекцию. Ниже представлен тот небольшой кусок знаний который я тогда вынес с этой 5ти минутной лекции.
Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 2 и более программиста) и студентам будет полезно. Кроме того, все изложенные ниже советы имеют альтернативу и могут быть использованы лишь частично.
Почему я приписал сюда студентов? Они же, казалось бы, одни работают над программой на зачет! Препод, когда принимает программу, справедливо считается вторым разработчиком, который в идеале без помощи студента должен понять, что там написано и как оно работает.
По сути говоря, на той лекции принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:
И лишь когда готов каркас из комментариев, следует писать код который будет реализовывать то, что описано комментариями.
Как упоминалось выше, данный принцип представляет собой модифицированный принцип, хорошо зарекомендовавшего себя TDD. Тут следует понимать, что отступление от комментариев, в отличии от отступления от логики тестов, не приведет к тяжелым последствиям, ну разве что придется комментарии переписывать
Теперь представим «чисто гипотетическую» ситуацию, когда уже имеется код в 200 000 строк, написанныйгениальным программистом криворуким индусом и не содержит ни строчки комментария. Однако вам необходимо, мало того что убить этого программиста понять этот код, но и сопровождать его в дальнейшем. Вы даже разобрались в этом коде, и будучи приличным человеком, решили дополнить код комментариями для, так сказать, будущих поколений. Но возникает вопрос: как?
Ответ на этот вопрос довольно прост: комментируем сущности от родителя к потомку: класс -> метод -> код внутри метода (если необходимо).
Вполне логично будет задуматься: а что не нужно комментировать. Комментировать не надо в двух случаях (один из них поясняет почему пример кода выше был сильно утрированный):
Относительно второго пункта стоит немного пояснить и привести пример: вставка 100 строк ассемблера код на C! Вы на нее смотрите и пишите комментарий // Многа букаф! Ниасилил
После этого человек пришедший после вашего увольнения на ваше место видит этот комментарий и… все! Он даже не будет пытаться в нем разобраться и эта ваша запись будет клеймом на этом куске кода до тех пор пока его не уберут (либо код, либо комментарий).
В заключение могу сказать, что искусство написания комментариев является неотъемлемой частью искусства программирования, поэтому комментарии писать надо, и, как бы пафосно это не звучало, но написанию качественных комментариев надо учиться.
Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 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! Вы на нее смотрите и пишите комментарий // Многа букаф! Ниасилил
После этого человек пришедший после вашего увольнения на ваше место видит этот комментарий и… все! Он даже не будет пытаться в нем разобраться и эта ваша запись будет клеймом на этом куске кода до тех пор пока его не уберут (либо код, либо комментарий).
Напоследок
В заключение могу сказать, что искусство написания комментариев является неотъемлемой частью искусства программирования, поэтому комментарии писать надо, и, как бы пафосно это не звучало, но написанию качественных комментариев надо учиться.