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

Основное

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

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

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

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

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

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

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

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

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

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

   Шаблон.st

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

   // Иванов И.И. 06.03.2024 OPSFIN-1234

   • при наличии системы контроля версий — не требуется

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

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

   Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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