Комментарии. Если вы YouTuber; они, вероятно, проклятие вашего существования. Если вы программист; они могут спасти жизнь. В этой статье я объясню вам, почему я так люблю комментировать свой код, и, надеюсь, убедить вас начать больше комментировать свой код.

На прошлой неделе мне пришлось программировать войну карточных игр на JavaScript. Для начинающего программиста это было непростой задачей.

Как мне подойти к этому?

Что входит в программирование карточной игры?

Почему, ну почему это должна быть карточная игра?

Да, сначала я был очень напуган.

Первый шаг к решению проблемы — понять, в чем проблема. Для меня обсуждение проблемы действительно может помочь мне приблизиться к решению. Когда вы программируете, отличный способ обсудить проблему — написать ее простым английским языком; и мы можем сделать это с помощью комментариев! Сделаем пример.

Предположим, вам поручили создать функцию, которая вычисляет и возвращает диаметр круга с заданным радиусом. Давайте определим нашу проблему, используя комментарии.

Теперь, когда мы определили нашу проблему, давайте начнем писать наше решение, обязательно комментируя по мере продвижения. Для этой задачи может быть полезно оставить комментарий с формулой для нахождения диаметра.

Теперь я знаю, что это очень простой пример, поэтому я покажу вам немного более сложный. На этой неделе на General Assembly мы только начали изучать управление элементами DOM и использование API. Чтобы помочь себе понять материал, я следил за кодированием инструкторов, обязательно оставляя множество комментариев по пути, чтобы я мог оглянуться назад и понять, что все делает.

Эти комментарии действительно пригодятся, когда мне нужно оглянуться назад и вспомнить, как сделать что-то вроде создания нового элемента или доступа к ответам на выборку API.

Комментарии также могут дать вам хорошую передышку в вашем коде. Разбор строки кода за строкой может быть утомительным; петля за петлей; функция за функцией. Дайте себе немного места, четко комментируя и определяя части вашего кода, — это отличный способ разбить блоки кода, чтобы сделать его более удобоваримым.

Еще одно полезное применение комментариев — использовать их как способ регистрации проблем в коде. Не удалось выяснить конкретную проблему? Оставьте себе комментарий и объясните, в чем проблема. Создан ли новый фрагмент логики взлома кода где-то еще в вашем коде? Оставьте комментарий, объясняющий, что происходит. Даже если вы еще не можете понять проблему, важно напоминать себе, что есть проблема, которую нужно решить, и где она находится. Вы также столкнетесь с ситуациями, когда вам просто нужно сделать перерыв на час или два, или, может быть, вы собираете его на ночь, но вы еще не совсем закончили свой код. Оставьте себе комментарий в качестве напоминания! Напомните себе, что вы делали, почему вы это делали и какую проблему вы пытались решить. Нет ничего хуже, чем вернуться к куску кода через день или два и понятия не иметь, какого черта вы пытались сделать.

Не забывайте быть конкретным! Нет смысла писать комментарии для себя, если вы их потом не поймете. Помните, что вы можете писать эти комментарии простым английским языком; компилятор никогда не увидит этот материал! Напишите себе целый абзац, если вам нужно. Все, что поможет объяснить вам или кому-то еще, кто будет читать ваш код.

Также очень важно помнить, что вы не всегда будете единственным, кто просматривает ваш код. Как инженер-программист, скорее всего, вы будете работать в команде с несколькими людьми. Вашим товарищам по команде нужно будет понять ваш код. Они должны иметь возможность быстро взглянуть на это, понять, что вы делаете, почему вы это делаете и как вы это делаете. Легче ли читать каждую строчку и расшифровывать, что все это значит, или проще просто прочитать красиво отформатированный комментарий над каждой функцией, который объясняет, почему она существует? В реальных условиях важно помнить о таких вещах.

Еще одна важная вещь, которую нужно понимать, когда дело доходит до любой работы по программированию в реальном мире, заключается в том, что вы будете работать с кодом, который состоит из тысяч и тысяч строк. Просто взгляните на файлы кода JS любой веб-страницы (используйте инструменты разработчика! Вы увидите кое-что интересное). Главная страница Google? 1370 строк кода. Твиттер? 8305 строк кода. YouTube? 115069 строк кода! Представьте, что вы пытаетесь прочитать такой объем кода и не оставить никаких комментариев.

Комментарии — чрезвычайно полезный инструмент в наборе инструментов разработчика. Есть причина, по которой разработчики языков программирования дают вам такую ​​возможность. Это легко сделать и действительно может спасти жизнь, когда вам это нужно. Полюбите эту клавишу с косой чертой и //прокомментируйте свой код!