Что за цифры в комментариях
Перейти к содержимому

Что за цифры в комментариях

  • автор:

Правила и рекомендации по комментированию в коде

Всем привет! Меня зовут Кристина Пешне, и я работаю младшим разработчиком веб-приложений в компании «ДоксВижн». Сегодня хочу представить статью о правилах комментирования в коде. Я не хочу сказать, что рекомендации, представленные в данной статье, являются аксиомами. Нет, всегда найдутся две стороны: на одной стороне будут те, кто согласен с представленными рекомендациями, на другой — те, кто не согласен. Разнообразие мнений — это нормально и прекрасно.

Моё мнение, отражённое в данной статье, основывается на книге «Чистый код» Роберта Мартина.

Неужели хороший код не нуждается в комментариях?

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

Хорошие комментарии

Если эти комментарии присутствуют в вашем коде — это хорошо.

Юридические комментарии

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

/* * animate.css -https://daneden.github.io/animate.css/ * Version - 3.7.2 * Licensed under the MIT license - http://opensource.org/licenses/MIT * * Copyright (c) 2019 Daniel Eden */

Большинство IDE позволяют автоматически сворачивать подобные блоки комментариев, чтобы они не загромождали остальной код.

Информативные комментарии

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

// Поиск по формату: kk:mm:ss EEE. MMM dd. yyyy сonst timeMatcher = new RegExp('\\d*:\\d*:\\d* \\w*. \\w* \\d*. \\d*');

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

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

Прояснение, представление намерений, пояснения к поведению

Иногда бизнес-требования ставят перед программистами задачи, решение которых трудно сделать интуитивно понятным для других разработчиков, если они не читали требования к задаче. Такие комментарии добавляют контекст к неинтуитивному решению, помогают разобраться с деталями кода, описывают намерения, заложенные в решении. Например, когда проводится работа с библиотекой, неочевидна бизнес-логика или описываются особенности в браузере IE.

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

Также такие комментарии часто помогают объяснить магические числа в коде.

// Для дополнительных задач требуется добавлять префикс перед идентификатором, чтобы он не совпадал с каким-либо из id выездов orderStateDTO.setOrderId("f_" + additionalTask.getId());

Комментарии TODO

Содержат пометки на будущее, информацию о том, что важно сделать, но не сейчас. Например, когда в будущем нужно сделать какой-то рефакторинг или сделать что-то, когда будет реализована зависимая часть кода. Большинство IDE позволяют вывести эти комментарии TODO в отдельное окно, что очень удобно.

После реализации основной логики какой-то задачи можно вернуться к таким комментариям и реализовать то, что ещё не было сделано, но необходимо. То есть получаем чек-лист на будущую работу, чтобы не искать потом по всему коду то, что вы забыли дописать. Это классический вариант технического долга. Можно больше не записывать себе задачки на листочке, а писать их прямо в коде!

// TODO: Удалить после удаления класса GroupTaskPanel // TODO: Проверить логику с приходящим значением null

Проблема таких комментариев в том, что они редко просматриваются и не актуализируются. Поэтому если вы используете такие комментарии, просматривайте их периодически и удаляйте ненужные.

Комментарии Jsdoc в общедоступных API (Это актуально также для аналогичных инструментов документирования в других языках)

Если код хорошо документирован в общедоступном API, с ним приятно и легко работать. В таком случае рекомендуется писать комментарии, которые будут упрощать формирование документации. Это документация метода или класса, которая показывается, когда вы генерируете документацию из вашего кода или когда вы наводите мышкой на название метода, и там показывается его Jsdoc (необходимые параметры, их типы, возвращаемое значение).

Jsdoc стоит использовать только с public методами и никогда с private методами. Private методы могут меняться без предупреждения, и в общедоступной документации они не описываются.

/** * Складываем числа * * @param first — первое число * @param second — второе число * @returns * */ function add(first, second)

Усиление

Комментарий такого рода подчёркивает важность обстоятельств, которые неочевидны с первого взгляда. Комментарий обращает внимание на то, что делает код, и на то, что его нельзя удалять. Свидетельствует о том, что код играет важную роль. Ведь всегда найдётся инициативный джун, рвущийся зарефакторить код и удалить пару лишних строчек 🙂

// Вызов trim() важен. Он удаляет начальные пробелы, чтобы строка успешно интерпретировалась как список let listItemContent = match.group(3).trim();

Предупреждение о последствиях

Это важные пояснения, которые предупреждают о том, что могут возникнуть проблемы после внесения определённых исправлений. Это как оберег к вашему коду от плохих изменений, чтобы потом не ломать голову, что же сломалось?!

// Don't lower more than 500ms, otherwise there will be animation-problems with the Safari toolbar setInterval(function() < $(window).scrollTop(-1); resize(); >, 500);

Плохие комментарии

Бормотание или непонятные комментарии, шум

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

// WTF. Refactor this! // Не грусти, я тоже не понимаю, что здесь происходит:(

Избыточные комментарии

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

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

// вспомогательный метод: возвращает деление двух чисел, когда второе не равно 0 function numbersDivision(a,b) < // Если знаменатель равен 0, то возвращается null if(b==0) < return null; >// результат метода return a/b; >

Журнальные комментарии, ссылки на авторов

Нередко разработчики указывают, в рамках какой задачи были исправлены те или иные строки. На самом деле, современные системы Git и IDE позволяют узнать, кем и в рамках какой задачи изменён код. Данные о правках можно найти в системе контроля версий. К тому же зачастую рефакторинг происходит в рамках других задач, и комментарий становится недостоверным.

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

// Добавлено Иваном // Изменено в рамках задачи Task-675 // Поправлено 05.10.2019

Закомментированный код

Если вы решили закомментировать код вместо того, чтобы от него избавиться, то лучше не стоит. Закомментированный код накапливается, а коллеги могут не удалять его, думая, что он важен. Не стоит складировать старый код, если можно в любой момент в системе контроля версий посмотреть нужную версию и вернуть необходимый участок кода. Удалять закомментированный код стоит целиком.

Окружение постоянно подвергается рефакторингу, а закомментированный код не меняется и теряет свою актуальность. Когда вы захотите его раскомментировать, он будет абсолютно непонятен и даже может не компилироваться, так как вокруг будут уже совсем другие переменные и методы. И тогда мы идём к системе контроля версий, чтобы понять, что и зачем там было. Лучше добавить комментарий в Git, зачем был удалён тот или иной блок кода.

Позиционные маркеры

Часто в комментариях разработчики используют слэши, минусы, звёздочки и пр., пытаясь таким образом отделить блоки кода. Если вам захотелось отделить блок кода, значит пора выделить его в отдельный метод.

/////////////////////////////////////////////////////////////////// ********************** комментарий **********************************

Комментарии за закрывающейся фигурной скобкой

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

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

try < while (что-то) < много строчек >// while много строчек > // try

Недостоверные комментарии

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

Обязательные комментарии

Некоторые компании заставляют разработчиков писать комментарии, считая, что код будет понятнее. Это неправильно. Это создаёт лишний мусор и не улучшает качество кода. Гораздо продуктивнее заставлять разработчиков правильно называть функции и классы, чем писать комментарии.

Заключение

Я считаю, что главное — это понимать, что комментарий не улучшит плохой код. Если очень хочется написать над методом то, что он делает, подумайте: может, из этого текста комментария сделать название этого метода, сократив и оставив важную часть, тогда этот комментарий и вовсе не понадобится. В большинстве случаев ваши намерения должны быть видны из кода, а не из комментариев.

Есть несколько тезисов из книги, которые, на мой взгляд, лучше всего отображают мнение автора о комментариях:

  • Не комментируйте плохой код – перепишите его.
    • Код должен говорить сам за себя.
    • Код развивается, а комментарии – нет.
    • У вас не получилось написать код так, чтобы его можно было понять без комментариев.
    • Каким бы хорошим ни был комментарий, он не оправдывает плохой код.
    • Комментарий должен отвечать не на вопрос «что делает код», а на вопрос «зачем».
    • Лучше делать код понятным сразу, чем пытаться объяснить его с помощью комментариев.
    • IT-стандарты
    • Карьера в IT-индустрии
    • Лайфхаки для гиков

    о цифрах в комментариях

    Плюсы и минусы в комментах ставят пользователи, которые или согласны или не согласны с комментарием.
    Один человек — один плюс. или минус.
    Повлиять Вы, конечно, можете, нажимая на кнопки справа от комментариев — одна соответствует положительной оценке, другая — отрицательной.
    Но я Вам советую о них не думать :)))

    Еще один совет — если Ваш постинг НЕ заметили, не нужно публиковать его снова. Пожалуйста!
    Проще, оставить внутри него коммент, тогда его обязательно увидят.

    По поводу вопроса в ваших предыдущих трех (. ) постах. В Москве очень много магазинов. Скидки бывают и в Триал-Спорте, и в КАНТе. Плюс, Вам уже советовали «Пилигрим», правда, я не уверена, что там будут скидки, но выбор обуви у них хороший. Вообще, можно съездить в торговый центр «Экстрим» — на м. Речной Вокзал, там много павильонов!

    9Aclimber, 02.10.2009 19:36

    Привет!
    Очень интересно, а почему пропал мой комментарий по адресам обувных магазинов?)))) Стоит брендовый фильтр)))) конкурентов не предлагать?))))

    robinsya, 02.10.2009 19:43

    О каких конкурентах Вы говорите? Risk.ru вдруг стал торговать обувью, а мне об этом не сказали? Интересненько.

    А вообще, ищите свой комментарий в ДРУГОМ посте. Если уж Вы сами не помните, где оставляете комменты, то я вам вряд ли смогу ответить на вопрос, куда они пропадают из постов, которые вы НЕ комментировали.

    duna, 02.10.2009 11:58

    спасибо за подсказку! по поводу 3-х постов — это получилось от того, что разбирался, как их организовывать, приношу свои извинеиния!

    Что означают цифры в комментариях к фотографиям из инстаграма? Например, 1/1 или 2/3

    Скорее всего, комментарий номер 2 из трёх, или фотография номер 2 из трёх.

    тот, кто написал такой комментарий хочет сказать то что, если вы поставите 2 лайка ему под фото, то он поставит вам тоже 2 лайка, или за 2 лайка 3 лайка и так далее. То есть первое число в дроби показывает сколько мы должны поставить, а второе число — сколько поставят вам. Это намного короче чем писать каждый раз «за 2 лайка поставлю 3 лайка, взаимно».

    Похожие вопросы

    Что за цифры в комментариях

    Что за цифры в комментариях в контакте?

    наверх

    вниз

    zerecky
    Рейтинг: 0 / -2

    — написано 2-12-2012 00:09 zerecky

    Постоянно вижу в комментах что то типа (245324908). Что это значит?

    Glas
    Рейтинг: 64 / -20

    — написано 2-12-2012 00:18 Glas

    где это? Не видел ниразу, может тайная секта?))

    sunderlend
    Рейтинг: 1307 / -290

    — написано 2-12-2012 01:30 sunderlend

    «ну вот, теперь он и вас тоже посчитал. » (С) козленок, который умел считать

    zerecky
    Рейтинг: 0 / -2

    — написано 2-12-2012 10:34 zerecky

    quote: где это? Не видел ниразу, может тайная секта?))

    Говорят, школолольный язык) Вчера пока срался в личку с одним школьником-педиком, он мне раза 3 комбинацию цифр отправил))

    PAPA.
    Рейтинг: 342 / -116

    — написано 2-12-2012 10:58 PAPA.

    Школьник-педик,дожили.

    Glas
    Рейтинг: 64 / -20

    — написано 2-12-2012 11:08 Glas

    Автор — эксперт по спорам со школьниками?

    Ижев_чанин
    Рейтинг: 1 / -7

    — написано 2-12-2012 11:37 Ижев_чанин

    quote: Вчера пока срался в личку с одним школьником-педиком

    Педофилия? Как можно спорить со школьником, да ещё и с педиком осознанно взрослому человеку?

    zerecky
    Рейтинг: 0 / -2

    — написано 2-12-2012 11:46 zerecky

    Я ж с целью поприкалываться) Тем более, что речь идет о подобном:

    PAPA.
    Рейтинг: 342 / -116

    — написано 2-12-2012 12:11 PAPA.

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

    zerecky
    Рейтинг: 0 / -2

    — написано 2-12-2012 12:29 zerecky

    Да не об этом речь то блин) Что за цифры, мне интересно) Гугление ничего не дает)

    PAPA.
    Рейтинг: 342 / -116

    — написано 2-12-2012 12:35 PAPA.

    Скрин в студию,хорош нам головы морочить

    CrAsssH
    Рейтинг: 1 / 0

    — написано 2-12-2012 13:35 CrAsssH

    quote: Originally posted by zerecky:

    245324908

    вбил цифры вконтакт выдало следующее у одной девочки:
    101167 и
    53913 в
    50305 не
    42123 что
    35629 я
    32191 на
    31815 с
    27913 он
    22305 как
    21715 а
    21003 то
    16077 это
    15681 все
    15183 но
    14793 его
    13610 так
    13436 к
    12620 же
    12498 она
    11426 у
    11339 вы
    11304 по
    11077 да
    11071 за
    9421 меня
    9261 бы
    8839 ты
    8796 мне
    8538 было
    8517 о
    8178 от
    8136 из
    8105 только
    7906 ее
    7559 еще
    6889 вот
    6272 был
    5850 ему
    5792 нет
    5715 теперь
    5648 уже
    5574 даже
    5297 до
    5168 ну
    5159 когда
    4996 ни
    4964 ли
    4802 вдруг
    4733 быть
    4699 если
    4448 него
    4388 вас
    4244 уж
    3987 вам
    3842 или
    3841 ведь
    3830 для
    3801 себя
    3785 сказал
    3776 может
    3757 они
    3708 есть
    3685 во
    3685 нибудь
    3680 их
    3625 очень
    3596 мы
    3516 тут
    3375 была
    3302 сам
    3247 опять
    3220 ничего
    3090 со
    3066 чем
    3054 того
    3021 раз
    2947 не
    2939 тебя
    2845 там
    2836 тебе
    2812 потому
    2802 себе
    2771 где
    2766 потом
    2711 ей
    2707 по
    2707 человек
    2669 под
    2664 без
    2601 тогда
    2598 будто
    2564 ж
    2544 ней
    2497 этого
    2490 наконец
    2477 чтобы
    2466 этот
    2453 совсем
    2434 кто

    zerecky
    Рейтинг: 0 / -2

    — написано 2-12-2012 15:01 zerecky

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *