Найти: на
Комментарии в коде, часть 2
Подпишитесь на новости



Внимание! Сайт переехал на http://бизнесплюспермь.рф

Разработка программ: комментарии в коде.

Важность комментариев

О нужности/бесполезности комментариев сказано много. Главные аргументы противников комментирования кода таковы:

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


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

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

    Ошибки комментирования кода

    Причудливый стиль комментирования

    Рассмотрим пример:

    // Переменная		Смысл
    // ---------------	---------
    // Х................Координата Х
    // У................Координата У
    // Z................Координата Z
    

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

    Еще пример:

    //***********************************************
    // * Процедура CalcMatrix                       *
    // * Назначение – вычисление обратной матрицы   *
    // * Параметры:                                 *
    // * Матрица – экземпляр класса Matrix          *
    //                                              *
    //***********************************************
    

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

    //***********************************************
    // Процедура CalcMatrix
    // Назначение – вычисление обратной матрицы
    // Параметры:
    // Матрица – экземпляр класса Matrix
    // **********************************************
    

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

    // Здесь мы просто комментируем
    // !!! А вот здесь очень важное замечание!
    // --- Или вот так!
    

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

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

    Пишите комментарии на уровне цели

    Другой распространенной ошибкой является написание комментариев, повторяющих код. Придумывая комментарий стремитесь ответить на вопрос ПОЧЕМУ?, а не КАК? Комментарии, объясняющие КАК что-то выполняется, относятся к уровню языка, а не проблемы. Цель операции остается неясной, поэтому такой комментарий избыточен:

    // Если флаг равняется Истина
    Если ФлагНового = истина Тогда.
    КонецЕсли;
    

    Комментарий сообщает то, что и так понятно. Нужен такой комментарий? Следующий вариант:

    // Если создается новый Документ
    Если ФлагНового = истина ТогдаКонецЕсли;
    

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

    // Если создается новый документ «Заказ покупателя»
    Если ВидДокумента = Перечисления.ВидыДокументаЗаказПокупателя ТогдаКонецЕсли;
    

    Избегайте сокращений.

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

    Снижение производительности

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

    О комментариях можно сказать очень много. Здесь освещены лишь отдельные грубые ошибки. Более полная информация будет на наших вебинарах.

    Прокомментировать статью можно здесь

    Hosted by uCoz