Чистый код — комментарии

Чистый код — искусство комментирования

Комментарии

Комментарии к коду — не однозначная концепция. С одной стороны, комментарии используют для пояснения работы следующего кода. С другой стороны, одна из концепций “Чистого кода”: код должен быть понятным и без комментариев.

От сюда, обозначим основные концепции:

  • Комментарии быстро устаревают. Важно не забывать обновлять комментарии при обновлении следующего кода. Это известная проблема комментариев. Устаревшие комментарии могут быть вредны. Они описывают одно поведение, а алгоритм кода — другое, что путает программиста.
  • Комментарии увеличивают размер кодовой базы и время на изучение кода. Нужно прочитать не только код, но и комментарии, чтобы вникнуть в алгоритм. 
  • Есть такое заблуждение, что комментарии компенсируют плохой код. Например, пишем не очень понятный или запутанный код, а далее, в комментариях поясняем его работу. Лучше написать ясный и выразительный код, чтобы комментарии не потребовались
  • Замена комментариям — подходящие, говорящие имена переменных, методов и классов
  • Лучше удалять старый код, чем комментировать его. Закомментированный код со временем разрастается и создает большой объем бесполезного или вредного груза. 
  • В некоторых случаях комментарии уместны. Они будут мощным инструментом. 

Уместные типы комментариев:

  • Юридические комментарии в начале модулей или классов, копирайты
  • Пояснения к сложным регулярным выражениям или маскам
  • Если используются какие то стандартные имена из сторонних библиотек. При этом, мы не можем на них повлиять, но можем описать комментариями
  • Когда передают опыт использования или предупреждения (например, // код ниже может работать очень долго если количество записей в базе данных больше миллиона)
  • Комментарии TODO
  • Усиление значения какого то факта, если его значение может показаться неочевидным (например, //не удаляйте код ниже, так как это защита от…)
  • Комментарии вида APIdoc, необходимые для генерации авто-документации по методам АПИ

Чистый код — комментарии: 19 комментариев

Добавить комментарий

Ваш адрес email не будет опубликован.