Вы действительно делаете полезные комментарии в базе кода? Давайте разберемся.
Когда дело доходит до комментариев, технически нет ничего правильного или неправильного, но комментарии могут иметь большое влияние на эффективность. Они могут значительно облегчить жизнь разработчикам. Давайте взглянем на некоторые повседневные комментарии и посмотрим, как мы можем их улучшить.
Примеры комментариев
Давайте рассмотрим несколько примеров комментариев и посмотрим, как они работают. После этого мы можем определить некоторые правила, чтобы сделать комментарии более эффективными и полезными для разработчиков.
Пример №1: комментарий «Что?»
Взгляните на следующий пример и определитесь с этим стилем комментирования.
Комментарии кажутся дубликатами кода, а сам код уже очень удобочитаем. Комментарии в этом случае излишни и не нужны. Разработчики могут легко прочитать код и понять, что происходит. Давайте упростим этот пример.
Разве это не легче читать? Код не требует пояснений. Мы можем еще больше упростить это. Не с точки зрения комментариев, а с точки зрения многократно используемых и читаемых абстракций.
Как это читать? Это практически читается как книга. Найдите всех пользователей, увеличьте оценку для всех пользователей и, наконец, верните пользователей.
Читаемость кода очень важна, даже важнее хороших комментариев. Если ваш код очень сложный, абстрагируйте его, сделайте более читабельным. Неужели нет абсолютно стопроцентного способа сделать его проще и читабельнее? Затем добавьте короткий и четкий комментарий, объясняющий, что он делает.
Если вы можете выбирать только между читаемым кодом или кодом с хорошими комментариями - обязательно выбирайте читаемый код.
Пример # 2: скопированный комментарий
Комментарии выше вообще не соответствуют коду! Видя, как код похож на один из наших предыдущих примеров, комментарии, вероятно, были скопированы. Разработчик не обновил комментарии, чтобы они соответствовали коду.
Обязательно обновляйте свои комментарии при копировании существующего кода. Если вы обнаружите, что вам нужно скопировать код, обычно есть способ абстрагироваться от него и сделать его пригодным для повторного использования. Что вы думаете о следующем фрагменте кода?
Мы абстрагировались от логики массового обновления оценок пользователей и сделали ее повторно используемой в том смысле, что можно указать количество обновляемых оценок. Теперь мы можем повторно использовать его в обоих сценариях вместо того, чтобы копировать код.
Пример # 3: Длинный комментарий JSDoc
Что касается следующего комментария, я не ожидаю, что вы его прочитаете полностью, просто взгляните на него. Что вы думаете?
Код - это не книга. Хотя я полностью за комментарии JSDoc, если команда согласится, комментарии в коде должны быть эффективными. Необходимость читать комментарий JSDoc в течение 10 минут, прежде чем понять, что делает функция, не является моим определением эффективности.
Оставляйте комментарии строго к необходимой информации, краткое и понятное сообщение.
Если разработчики хотят читать статьи, они могут делать это на Medium, а не в кодовой базе. Если ваш комментарий такой длинный, высока вероятность, что разработчики его даже не прочитают. Они могут даже забыть обновить комментарий, так как попытаются его проигнорировать.
Пример # 4: Короткий комментарий JSDoc
Мы видели пример длинного комментария JSDoc, давайте теперь рассмотрим короткий комментарий JSDoc.
Это еще один крайний случай, но я был свидетелем такого рода комментариев в реальных кодовых базах, и это действительно происходит. Хотя это частично полезно для генерации JSDoc с ожидаемым результатом, оно даже не является полным, потому что в нем отсутствуют некоторые параметры.
Если вы все же решили использовать JSDoc в своей кодовой базе, не идите на полпути, делайте это правильно с самого начала и содержите в чистоте. Это дополнительные усилия, которые в конечном итоге окупятся за поддержку программного обеспечения. Будьте строги в запросах на вытягивание и следите за тем, чтобы комментарии были в хорошем состоянии.
Пример # 5: устаревший комментарий JSDoc
В этом примере мы видим, что разработчик забыл обновить комментарий JSDoc, чтобы он соответствовал тому, что на самом деле делает функция. Функция updateScoreForUsers теперь также дает 500 VIP-пользователям дополнительный балл! Это не описано ни в комментарии, ни почему это так.
Пример # 6: Комментарий почему
Это один из моих любимых типов комментариев. Давайте взглянем.
В этом случае мы можем понять, что VIP-клиенты должны получить 500 дополнительный балл. Невозможно запутать разработчика и случайно изменить такое поведение из-за неясных требований.
Мы добавляем в код полезную дополнительную информацию, но при этом делаем его кратким и понятным. Разработчики могли догадаться, почему для этого кода, но не уверены в этом. Этот дополнительный комментарий устраняет любые сомнения, и разработчикам не нужно бояться изменять функцию.
Конечно, требования тоже должны быть ясны. На практике исходные требования не всегда четко документируются. Это особенно актуально для приложений, которые были перемещены между разными командами разработчиков. В идеальных ситуациях с большой документацией и требованиями этот конкретный комментарий может не понадобиться.
Если мы посмотрим на второй комментарий относительно базы данных, мы увидим еще один хороший пример того, где комментарии могут быть полезны. Когда разработчики используют код нетрадиционным способом из-за определенных ошибок или ограничений, может быть полезно добавить комментарий почему, поскольку другие разработчики не поймут, почему это было установлено таким странным образом. Они могут даже удалить исправление и вызвать проблемы, если комментарий не предупредит их.
В какой-то момент я наткнулся на виртуальную машину, работающую внутри другой виртуальной машины из-за определенных ограничений в настройке, чтобы иметь возможность выполнить наши требования. Комментарий, в котором упоминается это ограничение и почему запускается вторая виртуальная машина, безусловно, полезен. В большинстве случаев нам не нужно комментировать происходящее, поскольку понятный и читаемый код должен это учитывать. Однако мы не можем знать, почему.
Резюме
Комментарии могут играть важную роль в разработке, однако, как правило, более важен читаемый код. Есть много разных способов написания кода, но вот несколько рекомендаций, которые я рекомендую:
- Пишите короткие и четкие комментарии: разработчики не хотят читать книги в базе кода.
- Объясняйте, почему, а не что: если код читается, «что» обычно не требует пояснений. «Почему» могут только догадываться или предполагать разработчики. Разработчики должны знать, что нельзя предполагать и не гадать!
- Поддерживайте свои комментарии: обновляйте их! Если вы измените код, вы также должны обновить все предыдущие комментарии, связанные с этим кодом. Ваши коллеги и ваше будущее будут благодарить вас за это.
- Сообщения об отмене фиксации пользователем: это может быть отдельная статья, но вам нужно приложить дополнительные усилия, чтобы сообщения о фиксации были понятными и полезными.
- Написание читабельного кода. Наличие читаемого кода важнее комментариев.
