Комментарии
Комментарии к коду — не однозначная концепция. С одной стороны, комментарии используют для пояснения работы следующего кода. С другой стороны, одна из концепций “Чистого кода”: код должен быть понятным и без комментариев.
От сюда, обозначим основные концепции:
- Комментарии быстро устаревают. Важно не забывать обновлять комментарии при обновлении следующего кода. Это известная проблема комментариев. Устаревшие комментарии могут быть вредны. Они описывают одно поведение, а алгоритм кода — другое, что путает программиста.
- Комментарии увеличивают размер кодовой базы и время на изучение кода. Нужно прочитать не только код, но и комментарии, чтобы вникнуть в алгоритм.
- Есть такое заблуждение, что комментарии компенсируют плохой код. Например, пишем не очень понятный или запутанный код, а далее, в комментариях поясняем его работу. Лучше написать ясный и выразительный код, чтобы комментарии не потребовались
- Замена комментариям — подходящие, говорящие имена переменных, методов и классов
- Лучше удалять старый код, чем комментировать его. Закомментированный код со временем разрастается и создает большой объем бесполезного или вредного груза.
- В некоторых случаях комментарии уместны. Они будут мощным инструментом.
Уместные типы комментариев:
- Юридические комментарии в начале модулей или классов, копирайты
- Пояснения к сложным регулярным выражениям или маскам
- Если используются какие то стандартные имена из сторонних библиотек. При этом, мы не можем на них повлиять, но можем описать комментариями
- Когда передают опыт использования или предупреждения (например, // код ниже может работать очень долго если количество записей в базе данных больше миллиона)
- Комментарии TODO
- Усиление значения какого то факта, если его значение может показаться неочевидным (например, //не удаляйте код ниже, так как это защита от…)
- Комментарии вида APIdoc, необходимые для генерации авто-документации по методам АПИ
I needed to thank you for this excellent read!! I definitely enjoyed every little bit of it. I have got you bookmarked to look at new things you postÖ
Excellent article. I certainly love this website. Keep writing!
По моему мнению Вы не правы. Могу отстоять свою позицию. Пишите мне в PM, поговорим.
Я извиняюсь, но, по-моему, Вы ошибаетесь. Пишите мне в PM, обсудим.
Совершенно верно! Идея отличная, поддерживаю.
не очень могло быть и лучше
Извините за то, что вмешиваюсь… У меня похожая ситуация. Давайте обсудим. Пишите здесь или в PM.
Огромное спасибо за помощь в этом вопросе, теперь я не допущу такой ошибки.
You have hit the mark. Thought good, I support.
It is remarkable, this amusing opinion
В этом что-то есть. Теперь мне стало всё ясно, благодарю за информацию.
Between us speaking, I would address for the help in search engines.
I agree with told all above. We can communicate on this theme.
Я конечно, прошу прощения, но это совсем другое, а не то, что мне нужно.
Вы быстро придумали такой бесподобный ответ?
Я извиняюсь, но, по-моему, Вы не правы. Предлагаю это обсудить.
позитивчег)))
Какие слова… супер, замечательная мысль
Very amusing opinion
Нда!