помню такое...
03.04.2019, 18:41
Я обычно не пишу больше, чем краткое описание метода, аля "метод дрочит кальмару". Мало того, что с комментами почти весь проект становится серым и приходится же ориентироватьс я в комментах а не коде, так за частую, уставшие кодеры, не соображая тратят половину времени, что бы дублировать код комментом, а собственно - нахуя?
Я вот пришёл к тому же выводу: комментарии нужны только для public API кода, более того, они должны раскрывать intention - намерение, цель с которой существует метод/класс/функция, то есть то, что не всегда можно передать в виде кода. А вот каким образом код это делает, должно быть понятно из него самого.
Интересный метод.
иногда имена функций и переменных получаются слишком громоздкими (5-8 слов) для полного понимания что куда и зачем, а использовать их приходится многократно, так что в таких случаях комментарии + короткие имена внутри чистой функции - это хорошо.
А в чем отличие документации от комментария? Картинка выше это скриншот кода стандартной библиотеки, да на основе этого комментария генерируется документация, но является ли комментарии документацией? Если опирается на определение комментария из википедии - нет. Ссылка https://ru.wikipedia.org/wiki/Комментарии_%28программирование%29
что это за язык, я сходу не опознал. скала какая-нить, не?
но я всё равно подозреваю, что в этом языке есть обычные камента двумя слэшами, а есть такие с тремя. которые потом можно при сборке собрать из исходников и сгенерить htmlку или pdfку с доками. и их можно юзать тока перед методами и классами, а простые каменты - хоть где, в телах методов и т.д.
и если говорить о простых каментах, которые в доки не попадают, то действительно, единственное, зачем их стоит юзать, - для описания того, что это за херня, на которую я смотрю, и почему не надо ее тут же быстро решительно выпилить из проекта. остальное вполне можно выразить самим кодом - будет только лучше.
но я всё равно подозреваю, что в этом языке есть обычные камента двумя слэшами, а есть такие с тремя. которые потом можно при сборке собрать из исходников и сгенерить htmlку или pdfку с доками. и их можно юзать тока перед методами и классами, а простые каменты - хоть где, в телах методов и т.д.
и если говорить о простых каментах, которые в доки не попадают, то действительно, единственное, зачем их стоит юзать, - для описания того, что это за херня, на которую я смотрю, и почему не надо ее тут же быстро решительно выпилить из проекта. остальное вполне можно выразить самим кодом - будет только лучше.
через 2 месяца пытаешься разобраться в своём же говнокоде
