3.3.6 Правила оформления исходных текстов, комментирование

     При оформлении пакета нужно руководствоваться следующим:

• запрешено использовать вложенные процедуры
• запрещены пустые строки внутри процедур или функций
• допустима только одна пустая строка между процедурами в теле и в заголовке
• все отступы должны быть кратны двум символам
• запрещено использовать отступы перед словом PROCEDURE/FUNCTION при декларации процедуры/функции как в теле так и в заголовоке
• обязателен отступ в два символа для локальных переменных, аргументов процедур, текста внутри begin ... end

     При комментировании заголовка пакета используются два вида комментариев: общий комментарий пакета и комментарии процедур/функций пакета.

1. Комментарий располагается в заголовке пакета сразу за строкой CREATE OR REPLACE ... AS
2. Комментарий начинается строкой:

       

   /**

   и заканчивается строками:

       

   @headcom */

3. Комментарии располагаются в заголовке пакета.
4. Комментарии заканчиваются словом @headcom на отдельной строке.
5. Комментарии состоят из двух частей: описательной и истории модификации. Описательная часть идет перед историей модификации.

     Требования к описательной части комментария:

1. В первом предложении указывается имя модуля.
2. Следующие предложения - описание назначения пакета и места вызовов процедур пакета.
3. В тексте описания явно не выделяются части с названием модуля и описанием назначения и мест вызовов.
4. Максимальная длина строки - 80 символов.

     Требования к истории модификации:

1. История модификации заключается в теги <pre></pre>
2. Открывающий и закрывающий теги <pre> располагаются на отдельных строках без отступов.
3. Первая строка - "История модификации:" с отступом в два символа.
4. Следующие строки - записи о произведенных изменениях.

     Критерии необходимости внесения записи об изменениях определяются документами, регламентирующими процесс создания и сопровождения ПО.

     Требования к оформлению записи о произведенных изменениях:

1. Записи об изменениях должны располагаться таким образом, что сведения о последних изменениях пакета будут находиться в верхней части историии.
2. Запись состоит из трех полей: даты, автора и описания изменений. Поля обязательно должны располагаться в таком порядке.
3. Все поля очередной записи должны располагаться точно над соответствующими полями предыдущей записи.
4. В поле "Дата" указывается дата внесения изменений в формате ДД-ММ-ГГГГ.
5. В поле "Автор" указывается фамилия и инициалы автора изменений.
6. В поле "Описание" указывается характер внесенных изменений.
7. Отступ поля "Дата" от края - 2 символа
8. Расстояние между полями "Дата" и "Автор" - 2 символа.
9. Расстояние между полями "Автор" и "Описание" - минимум 2 символа.
10. Если длина фамилии и инициалов очередного автора изменений больше ширины, отведенной для поля "Автор", поле "Описание" отодвигается вправо на необходимое количество символов.

     Пример правильно комментированного пакета:

create or replace package hosp_spr_common_pkg as
/**
  Модуль "Больницы общее". Реализация работы со справочниками, общими
  для больниц. Вызывается при работе со справочниками: юридических лиц,
  возрастов, договоров, общих справочников. Вызывается при модификации
  информации о юридических лицах, договорах.

<pre>
  История модификации:
  28-04-2003  Сак А.А.         Реализация справочников SPR_INSURE,
                               SPR_INSURE_DEP, SPR_TFOMS, SPR_CONTRACT
  24-04-2003  Прудовский П.В.  Добавил INSURE_DISPLAY, INSURE_SAVE
  01-04-2003  Сак А.А.         Справочник AGE_GROUPS,
                               процедура CREATE_AGE_GROUPS_SCRIPT,
                               оформление.
  19-08-2002  Сак А.А.         Процедура генерации справочников 
                               из HOSP_SPR_DESCRIBE.
                               Переделал из генератора STAC_SPR_DESCRIBE.
  05-07-2002  Прудовский П.В.  Создал
</pre>
@headcom
*/
...

3.3.6.1. Пример правильно оформленного пакета

create or replace package doc_mail_card_core_pkg is
/**
  Модуль "Учет корреспонденции". Реализация работы с серверной частью модуля.

<pre>
  История модификации:
  20-05-2003  Христюк А.С.  Создал.
</pre>
@headcom
*/

/** Процедура для сохранения информации в таблице DOC_MAIL_CARD
    @param doc_mail_card_rec  Запись с данными
*/
procedure int_doc_mail_card_save (
  doc_mail_card_rec in out doc_mail_card%rowtype
);

/** Процедура для удаления информации в таблице DOC_MAIL_CARD
    (корреспонденция).
    @param cor_id       Идентификатор
*/
procedure int_doc_mail_card_delete (
  cor_id in doc_mail_card.cor_id%type
);
end doc_mail_card_core_pkg;
/
create or replace package body doc_mail_card_core_pkg is

procedure int_doc_mail_card_save (
  doc_mail_card_rec in out doc_mail_card%rowtype
) is
begin
  if doc_mail_card_rec.cor_id is null then
    select sq_doc_mail_card.nextval into doc_mail_card_rec.cor_id from dual;
    insert into doc_mail_card(cor_id
                             ,doc_type_cod
                             ,card_id
                             ,in_num
                             ,in_date
                             ,out_num
                             ,out_date
                             ,org_name
                             ,fio
                             ,summary)
    values(                   doc_mail_card_rec.cor_id
                             ,doc_mail_card_rec.doc_type_cod
                             ,doc_mail_card_rec.card_id
                             ,doc_mail_card_rec.in_num
                             ,doc_mail_card_rec.in_date
                             ,doc_mail_card_rec.out_num
                             ,doc_mail_card_rec.out_date
                             ,doc_mail_card_rec.org_name
                             ,doc_mail_card_rec.fio
                             ,doc_mail_card_rec.summary);
  else
    update doc_mail_card set doc_type_cod = doc_mail_card_rec.doc_type_cod
                            ,card_id      = doc_mail_card_rec.card_id
                            ,in_num       = doc_mail_card_rec.in_num
                            ,in_date      = doc_mail_card_rec.in_date
                            ,out_num      = doc_mail_card_rec.out_num
                            ,out_date     = doc_mail_card_rec.out_date
                            ,org_name     = doc_mail_card_rec.org_name
                            ,fio          = doc_mail_card_rec.fio
                            ,summary      = doc_mail_card_rec.summary
    where                    cor_id       = doc_mail_card_rec.cor_id;
  end if;
end;

procedure int_doc_mail_card_delete (
  cor_id in doc_mail_card.cor_id%type
) is
begin
  delete from doc_mail_card where cor_id=int_doc_mail_card_delete.cor_id;
end;

end doc_mail_card_core_pkg;
/