Если у Вас нет феноменальной памяти

Добавить свою публикацию

для этого требуется регистрация

YPermitin

08.04.2013

Программисту > 1С 8.х

Суть проблемы

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

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

Правильный подход

Рассмотрим несколько случаев, когда необходимо комментировать код.

Изменение существующего модуля

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

// ++ YPermitin - ТЗ 555 - 06.04.2013
// До изменения
//Если МассивОбъектов.Количество()>0 Тогда
// Возврат;
//КонецЕсли;
// После изменения
Если МассивОбъектов.Количество()>0 Тогда
	Если ТипЗНЧ(МассивОбъектов[0]) = Тип("ДокументСсылка.ДоверенностьНаПолучениеТоваров") Тогда
		Если МассивОбъектов[0].Товары.Количество()=0 Тогда
		    Сообщить("'В табличных частях нет ни одной позиции!!!'");
			Возврат;
		КонецЕсли;
	КонецЕсли;
КонецЕсли; 
// --

Такой же принцип относится ко всем ситуация модификации как программного кода, так и текстов запроса и так далее. Если изменяется одна строка в запросе, то необязательно комментировать весь запрос и затем приводить новый текст с модификацией. Можно комментировать изменение подобным образом прямо в тексте запроса. Добавление новой процедуры/функции

Добавление процедуры/функции

При добавление процедуры или функции обязательно напишите ее назначение, передаваемые параметры и возвращаемый результат (для функции).

// Задать область печати объекта в табличном документе.
// Применяется для связывания области в табличном документе, с объектом печати (ссылка).
// Необходимо вызывать при формировании очередной области печатной формы в табличном
// документе.
// Параметры:
// ТабличныйДокумент - табличный документ - табличный документ печатной формы
// НомерСтрокиНачало - число - позиция начала очередной области в документе
// ОбъектыПечати - СписокЗначений - список объектов печати
// Ссылка - ссылка на объект ИБ - объект печати
//
Процедура ЗадатьОбластьПечатиДокумента(Ссылка) // YPermitin - ТЗ 555 - 06.04.2013
	
	Элемент = ОбъектыПечати.НайтиПоЗначению(Ссылка);

	// .....

КонецПроцедуры

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

Сложный алгоритм

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

// Процедура - обработчик события "ОбработкаПроведения".
Процедура ОбработкаПроведения(Отказ, РежимПроведения)	

// Инициализация дополнительных свойств для проведения документа
ПроведениеСервер.ИнициализироватьДополнительныеСвойстваДляПроведения(Ссылка, ДополнительныеСвойства, РежимПроведения);
	
// Инициализация данных документа
Документы.АвансовыйОтчет.ИнициализироватьДанныеДокумента(Ссылка, ДополнительныеСвойства);
	
// Подготовка наборов записей
ПроведениеСервер.ПодготовитьНаборыЗаписейКРегистрацииДвижений(ЭтотОбъект);
	
// Движения по денежным средствам.
ДенежныеСредстваСервер.ОтразитьДенежныеСредстваУПодотчетныхЛиц(ДополнительныеСвойства, Движения, Отказ);
	ДенежныеСредстваСервер.ОтразитьДенежныеСредстваКСписаниюСПодотчетныхЛиц(ДополнительныеСвойства, Движения, Отказ);
	
	// Движения по расчетам с поставщиками.
	ВзаиморасчетыСервер.ОтразитьРасчетыСПоставщиками(ДополнительныеСвойства, Движения, Отказ);
	ВзаиморасчетыСервер.ОтразитьРасчетыСПоставщикамиПоследовательность(ДополнительныеСвойства, ПринадлежностьПоследовательностям, Отказ);
	
// Движения по прочим расходам.
ДоходыИРасходыСервер.ОтразитьПрочиеРасходы(ДополнительныеСвойства, Движения, Отказ);
	
// Запись наборов записей
ПроведениеСервер.ЗаписатьНаборыЗаписей(ЭтотОбъект);
	
ПроведениеСервер.ОчиститьДополнительныеСвойстваДляПроведения(ДополнительныеСвойства);

КонецПроцедуры // ОбработкаПроведения()

В большинстве типовых конфигураций подробное комментирование программного кода отсутствует. И это понятно, ведь количество строк кода, в той же УПП, настолько велико, что его описание в комментариях может значительно увеличить срок разработки. Несмотря на это, писать описание к своему коду нужно, иначе вся ваша работа превратиться в "спагетти", в которой очень трудно разобраться.

Шаблоны

Для упрощения процесса написания комментариев в коде можно использовать собственные шаблоны. Например, создадим шаблон, добавляющий комментарий об авторе, номере тех. задания и текущей дате. Для этого откроем окно шаблонов текста через меню "Сервис->Шаблоны текста" или через команду главного меню.

Перед нами октроется окно редактирования нового файла шаблонов.

Назовем его "Собственный шаблон". В него добавим новый текст шаблона. Тогда настройки будут выглядеть следующим образом:

Самые важные параметры здесь задаются в поле "Автоматически заменять строку" и "Текст шаблона". Введенный текст "Ком" в поле заменяемой строки позволяет платформе определять в каких случаях нужно применить шаблон и предложить разработчику его использование. В текст шаблона не будем вдаваться подробно, поскольку изучив типовые шаблоны Вы сможете написать для себя шаблон любой сложности. Это очень просто. Чтобы шаблон был задействован при написании программного кода нужно добавить его в шаблоны (платформа предлагает сделать это автоматически при сохранении нового шаблона), и включить их использование в параметрах конфигуратора.

Тогда при наборе слова "Ком" платформа предложит ввести номер ТЗ и затем вставить следующий текст комментария:

Согласитесь, использование шаблонов весьма сэкономит Вам время.

Делайте выводы

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

предыдущие ()все