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

логирование

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

// Now we are going to convert Thing-Amajig-A to Thing-Amajig-B

Мы можем просто выдать ту же информацию, что и оператор регистрации.

logger.info(“Now we are going to convert Thing-Amajig-A to Thing-Amajig-B”)

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

Создавая нашу культуру, а также наши продукты, с 1824 года. ›› Открыть открытые роли

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

Тестирование - «Покажи, не говори»

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

Хороший нейминг

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

Разделение проблем

Что касается хорошего именования, нужны ли вашему коду комментарии, потому что он пытается делать слишком много вещей? Прежде чем объяснять, что он пытается сделать, проверьте, легко ли
разделить конкурирующие функции. Здесь применимы те же предостережения, что и для
выше, с хорошим именованием, мы не живем в идеальном мире, где весь код
будет преследовать одну цель, и иногда мы просто не увидим очевидного рефакторинга. < br /> Тем не менее, к повышению ясности кода всегда стоит стремиться, и
определенно стоит подумать минутку или около того, прежде чем пытаться вставить
проблему в комментарий.

Спецификация

Здесь я углубляюсь в территорию, которая будет во многом зависеть от того, на каком языке вы пишете. В AppsFlyer мы пишем большую часть нашего кода на Clojure, поэтому
часть того, что я буду обсуждать, будет конкретно для Clojure, но я постараюсь быть здесь как можно более общим
.

Под «спецификацией» я, очевидно, имею в виду Clojure Spec, но я также
думаю о многих других функциях, которые являются общими для языков, отличных от
Clojure. Например, используете ли вы тип данных,
который наиболее четко выражает ваше намерение. Хороший пример - Set vs a Vector. Если вы заботитесь о порядке
элементов в коллекции, то Vector - хороший выбор. Если вас не
заботит порядок и вам не нужны дубликаты, тогда Set - хороший выбор. Что делать, если вы заботитесь о порядке и не хотите
дубликатов? Многие языки предлагают отсортированный набор, который может удовлетворить ваш случай использования.

Точно так же, если вы работаете со строго типизированным языком,
вам не нужно добавлять документацию, в которой говорится, что первый аргумент должен быть строкой, а второй - числом. Это ясно
из сигнатуры функции. Если вы не владеете строго типизированным языком,
какие у вас варианты? Простой вариант, который должен работать практически везде, - это выразить в коде требования или контракт функции. Программирование в стиле контрактов может быть таким же простым, как написание кода в начале или в конце функции для проверки правильности аргументов и возвращаемых значений, однако многие языки программирования, включая Clojure, имеют некоторую встроенную поддержку этого стиля программирования. Используя стиль контракта, вместо того, чтобы писать в комментарии, что первый элемент должен быть строкой, это требование можно прописать прямо в коде.

Clojure Spec берет эти идеи и развивает их. Используя многофункциональную и открытую систему, вы можете указать разрешенные аргументы для ваших функций, включая ограничения между аргументами. Например, вы можете сказать, что первый и второй аргументы должны быть датами, а вторая дата должна быть после первой. Кроме того, вы также можете выражать ограничения между входными аргументами и выходными данными ваших функций. После того, как вы выполнили эту работу по спецификации - что не совсем просто - во многих случаях вы получаете автоматическое тестирование бесплатно. Поскольку Clojure теперь знает, какие типы ввода
разрешены, он может создавать случайные входные данные для вашей функции и проверять, соответствуют ли выходные данные функции
указанной вами спецификации. Многие из спецификаций
сами по себе довольно легко читать - подумайте о предикатах, таких как
`number?` Или `string?`, И вы можете написать свои собственные предикаты для конкретных объектов приложения. Если у вас есть спецификация для вашей функции, ограничивающая тип аргументов, которые принимает ваша функция, и то, как эти аргументы соотносятся с выходными данными функции, вряд ли останется много объяснений в комментариях. Clojure Spec в настоящее время находится в стадии разработки, но он показывает путь к строгости и безопасности на нетипизированном языке.

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

Кодирование проходит по вашим венам? "Присоединяйтесь к нам"!