Skip to main content

Префикс и комментарии

Основное​

  1. Каждый добавляемый объект метаданных должен содержать в своем наименовании префикс прф:

    // Шаблон
    прф<Наименование>

    // Примеры
    прфСотрудникиСервер
    прфСлужебныеНастройки

  2. Синоним метаданных не должен содержать наш префикс. Если нужно, чтобы новый объект отличался от типового т.к используется один и тот же синоним то используйте в конце наименования (Расширенный).

    Товары на складах (Расширенный)

  3. Комментарий в коде типовых модулей должен иметь следующий вид:

    //<Фамилия автора> - начало изменения [(IR/CR <номер запроса>)] <дата изменения> {{
    КОД
    //}} <Фамилия автора> - конец изменения

    Шаблон начала комментарий:

    // Иванов И.И. <?"", ДатаВремя, "ДФ=dd.MM.yyyy"> <?"Номер задачи"> {
    <?>

    Шаблон окончания комментарий:

    <?>// }Иванов И.И. <?"", ДатаВремя, "ДФ=dd.MM.yyyy">

    Шаблон.st

  4. При добавлении нового объекта в обязательном порядке требуется указать в поле комментарий причину добавления:

    // Иванов И.И. 06.03.2024 OPSFIN-1234
    • при наличии системы контроля версий - не требуется

  5. Описания добавляемых процедур должны начинаться с:

    // <Описание назначения процедуры/функции>
    //

    Например:

    //Функция преобразует строку в массив подстрок
    //
    // Параметры:
    // Стр  - Строка - Строка для преобразования
    // Разделитель - Строка - Разделитель подстрок (по умолчанию «;»)
    //
    // Возвращаемое значение - Массив  - Результат преобразования
    //
    Функция РазложитьСтроку(Знач Стр, Разделитель = «;»)

  6. Описание должно отвечать на вопрос: Что делает?, а не Как делает?

Описание процедур и функций должно быть кратким и емким.

Комментарии (об изменении с фамилией и датой) в модулях и методах с префиксом прф не оставляются (актуально при использование систем контроля версий). Также не нужно оборачивать новые методы комментарием в начале и в конце, по желанию может быть заполнена информация о методе (Смотри пример модулей от 1С).

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

Почему это важно?​

image

Снижается читаемости кода​

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

Избыточность информации​

Современные системы контроля версий, уже отслеживают изменения в коде с указанием автора и даты. Дублирование этой информации в виде комментариев в самом коде избыточно.

Быстрое устаревание информации​

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

Нарушение принципов чистого кода​

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

Отвлечение внимания​

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