Комментарии 15
Респект. Тоже думал плагин запилить по главреду, да все времени не было, ну и потом необходимость отпала.
Открыл код, но увлекся чтением комментариев ;)
Лучшие комментарии - их отсутствие.
Рекомендую почитать книгу Clean Code дяди Боба. После этого нужда в комментариях просто пропадёт сама собой, потому что ваш код начнёт комментировать сам себя и будет читаться как хорошая проза, по выражению автора :)
Ну конечно, а еше он говорит, что дебагеры не нужны и все TDD должно быть обмазанно. Напомните они там уже запилили Generics или снова оказалось, что рассуждать и делать разные веши?
Кнут, к примеру, продвигал идею литературного программирования. Комментарии сушествуют не потому, что кода достаточно, а потому, что код избыточен или контекстуально не полон, понимать надо.
Ну он вообще любит поговорить :-) И это здорово, потому что очень многие его мысли достойны внимания.
Я не могу припомнить ни одного философа, который не имел бы спорных утверждений. Но это не отменяет их главных идей. При их чтении наша задача состоит в том, чтобы отсеивать зёрна от плевел, используя критическое мышление.
Дядя Боб представляет свой взгляд на проблему развития и сопроводжения крупных проектов и предлагает рабочие способы для того чтобы код проекта, как это часто случается, не превратился со временем в помойку к которой все боятся прикоснуться.
Я много лет назад листал Clean Code и затем смотрел видео лекции дяди Боба, прочитанные им в универе, и нашёл их весьма здравыми. В результате мои подходы к дизайну модулей и стиль кодирования заметно улучшились.
Что касается комментариев в коде, то я могу проиллюстрировать это простым примером:
// Check to see if the employee is eligible for full benefits
if (employee.flags && HOURLY_FLAG && employee.age > 65) {
...
}Отдельный метод с говорящим именем выглядит намного лучше. Нагромождение деталей реализации не отвлекает внимания от бизнес логики.
if (employee.isEligibleForFullBenefits()) {
...
}
А теперь добавьте еще три-четыре условия в if и попробуй отразить это в имени. В энтерпрайзе не бывают простых примеров.
Как видно из приведённого мной примера, имя метода показывает что он делает, а не как он это делает. Всегда можно подобрать ёмкое имя для небольшого метода. Если же не удаётся этого сделать, то это является признаком того, что метод слишком сложен, и нужно его распилить, применив извлечение методов и классов. Каждый из них, в свою очередь, получит говорящее имя.
Увы, код, который комментирует сам себя, невозможно читать.
По элементарной, хотя бы причине: идентификаторы (имена) методов (да и вообще всего), должны ИДЕНТИФИЦИРОВАТЬ методы, то есть, отличать их друг от друга, а не описывать их. Имена банально должны быть как можно короче, чтобы ими пользоваться, если имена будут описывать сами себя, то они будут на несколько строк длиной.
Просто прочтите это (для доступа в сайту требуется VPN, спасибо Рокомнадзору):
https://refactoring.guru/ru/smells/long-method
Цитата:
Следует придерживаться такого правила: если ощущается необходимость что-то прокомментировать внутри метода, этот код лучше выделить в новый метод. Даже одну строку имеет смысл выделить в метод, если она нуждается в разъяснениях. К тому же, если у метода хорошее название, то не нужно будет смотреть в его код, чтобы понять, что он делает.
По поводу длины имён есть простое правило. Длина имени метода или класса обратно пропорциональна размеру его области действия (scope). Для переменных всё наоборот - чем меньше область, тем короче имя.
Дядя Боб (Robert C. Martin) идёт ещё дальше, и говорит:
Функция должна делать лишь одну вещь. Что такое "одна вещь"? Функция делает одну вещь если из неё невозможно извлечь другую функцию. Нужно последовательно извлекать функции до тех пор, пока это не станет уже невозможно. Каждой функции следует давать осмысленные, выразительные, удобопроизносимые имена, и помещать их в должным образом названные классы, пакеты и модули (правило касательно длины имён я привёл в предыдущем комменте).
Высокоуровневые методы располагаются выше по коду, детали релизации помещаются ниже. Чем глубже в детали, тем ниже помещается метод. Это позволяет легко читать код, состоящий из простых, коротких и удобопроизносимых имён методов, при необходимости спускаясь глубже и глубже в детали, насколько требуется. В результате мы получим семантическое дерево методов, которому можно следовать по именам, и проявим истинную сущнность ОО-структуры системы, над дизайном которой работаем.
Если в организации заботяться о соответствии нормам безопастности, то такой плагин не разрешат. Слать свои коментарии куда-то выглядит небезопасно.
Улучшаем комментарии с помощью плагина Comment Lint