Этот код слишком сложен. Я добавлю комментарий, чтобы помочь следующему разработчику.
Это, скорее всего, то, о чем каждый разработчик думал хотя бы раз в своей карьере и в большинстве случаев добавлял это.
Почему !commenting так важен?
JS предназначен для каламбура, но на случай, если вы не в курсе ! значит нет
Я начну с очевидного... независимо от того, на каком языке программирования вы пишете, это все равно ЯЗЫК программирования. (заглавные буквы не были ошибкой)
Например, когда вы идете по магазинам и ищете помощи у кого-то, вам нужно общаться на языке или способом, который вы оба понимаете, чтобы дать им контекст. Почему? ну как еще этот человек поймет? (не говорите на языке жестов... принцип тот же :P)
Давайте попробуем пример, когда мы неправильно выражаемся и просто используем комментарии, чтобы дать другому человеку понять, чего мы хотим.
Допустим, я хотел узнать, сколько стоят 2 бутылки воды, и единственное, что я сказал, было «2 бутылки денег»? что понял бы продавец? Давайте использовать комментарии, как мы это делаем при кодировании, чтобы дать больше контекста и сэкономить день. "Я имею в виду, сколько стоят 2 бутылки воды?" Скорее всего, вы получите озадаченное лицо и комментарий "почему вы так не сказали!"
Это то же самое, что я думаю, когда вижу что-то вроде этого
const plwat2 = (wtr=1) => wtr*2. //возвращает стоимость 2 бутылок воды
Этот комментарий необходим, потому что нет никаких сведений о том, что он возвращает, кроме двойного значения wtr. Но моя первая мысль: почему ты так не сказал!
Давайте рефакторим это, чтобы повысить читабельность
const costOf2WaterBottles = (waterBottlePrice=1) => waterBottlePrice * 2
…а теперь давайте попробуем прочитать еще раз
Стоимость 2 бутылок с водой — это функция, которая возвращает .. Стоп! Название функции говорит само за себя. Это ваша отправная точка, и теперь я знаю, чего жду от этой функции. Почему? Потому что я дал хорошее описательное имя функциям, которые показали намерение.
Продолжайте, чтобы увидеть, как читается остальное. стоимость 2 бутылок с водой — это функция, которая возвращает цену бутылки с водой * 2
имеет смысл, верно? ну, это было бы ... мы используем слова, поэтому у нас есть возможность именования и контекста при написании кода.
Конечно, это довольно простой пример, но логика применима к любому случаю, хотя я уверен, что кто-то может подумать «попробуйте применить это к 50 строкам кода и посмотрите, что получится…»
Мой ответ будет таким: 50 строк кода — это то же самое, что составить предложение из 50 строк. Будет ли это иметь смысл?
Комментарии — самая неподдерживаемая часть любой кодовой базы.
Можно было бы сказать, почему крайне непригодным для обслуживания. Ну, сначала мы должны подумать о наших процессах в цикле разработки, чтобы обеспечить обслуживание.
1) разработка самой функции
2) проверка кода
3) тестирование
4) развертывание
Из 4-х этапов только второй может быть рассмотрен.
Насколько легко можно пропустить или неправильно рассмотреть комментарии во время просмотра?
Я бы сказал, что очень просто, и причина в том, что нет реального процесса, который защитит вас от неправильных или устаревших комментариев.
Важной частью нашей реализации является тестирование. Не только вручную, но и с помощью модульных и автоматических тестов
Это, скорее всего, ответ на вопрос, почему нельзя добавлять комментарии. Как вы будете проверять свои комментарии? Как вы будете следить за тем, чтобы ваши комментарии не устарели? Что еще более важно, почему вы не используете модульные тесты? Если да, то зачем вам комментарии? Модульный тест — это документация вашего фрагмента кода. Это то, что требует правильных описаний. Почему? Потому что это часть процесса. Однако модульное тестирование — это совсем другая тема, которую мы рассмотрим в другой раз.
Важный вопрос, когда вы чувствуете побуждение написать комментарий:
Могу ли я прочитать этот фрагмент кода? Если ответ отрицательный, то никто не может. Даже если вы оставите комментарий и пересмотрите его через 2 месяца, чтобы что-то реорганизовать, потому что вам придется читать этот фрагмент кода построчно и понимать, что нужно изменить. Даже если ваш код описательный, вы бы это сделали, но разница во времени. Сколько времени вам понадобится, чтобы понять оба случая?
В наши дни в нашем распоряжении так много инструментов, которые делают комментарии устаревшими и ненужными
линтерами, функциями безопасности типов, модульными тестами, тестами автоматизации, инструментами сложности кода и, конечно же, документированием нашей функции, которая !комментирует наш код.
В конце концов, комментирование означает одну или две вещи
1) Код, который не говорит сам за себя, потому что вы не даете правильных имен переменных, классов, функций, поэтому необходимо объяснить некоторые вещи
2) Вы делаете слишком много вещей.
В любом случае комментирование спасет момент, но не причину.
Когда вы читаете код, вы должны его понимать. Наличие комментариев сводит на нет цель читабельного кода и допускает окна с плохо написанным кодом, потому что «ну, это было сложно, поэтому я добавил комментарий». Если вы можете писать хорошие комментарии и плохой код, попросите кого-нибудь помочь вам написать читабельный код. Переосмыслите имена переменных, функции и логику
Не используйте комментарии в качестве предлога для написания десятков или даже сотен строк кода, потому что единственное, что вы добавляете, — это сложность проекта. Нет такой вещи, как супер-пупер-функция, это беспорядок реализации, который только во время реализации можно прочитать и никто другой.
Комментирование спасет момент, но не причину!
Другими словами, код сложный или не описательный!
