Дополнительные разделы комментариев в заголовке функции Ada

Question

Когда читатель начинает читать код функции, он уже должен иметь очень хорошее представление о том, что он делает, как он это делает и с какими проблемами он может столкнуться. Я пытаюсь написать чистый, структурированный, хорошо прокомментированный код, который легко понять. И я читаю Руководство по стилю Ada и некоторые вещи, которые я недостаточно хорошо понял, что я могу написать для необязательных разделов (например: @Error_Handling, @Pre, @Post). Я хочу представить эту функцию в качестве примера. Используя приведенные выше рекомендации, можно получить стандартный заголовок функции:

--  ---------------------------------------------------------------------------
--  @Function: Arithmetic_Mean
--
--  @Description:
--    Function to find the mean of a numeric vector. The program should
--    work on a zero-length vector (with an answer of 0.0).
--  @Usage: (opt)
--  @Parameter:
--    +Num: Given array
--  @Return: Averages/Arithmetic mean or zero
--  @Error_Handling: (opt)
--  @Pre: (opt)
--  @Post (opt)
type Mean_Numbers is array (Natural range <>) of Float;
function Arithmetic_Mean (Num : Mean_Numbers) return Float is
   Sum : Float := 0.0;
begin
   if Num'Length > 0 then
      while Num'First <= Num'Last loop
         Sum := Sum + Num(Num'First );
      end loop;
      return Sum / Float (Num'Length);
   end if;
   return 0.0;
end Arithmetic_Mean;

И вот еще один пример:

-------------------------------------------------------------- ... --
--  @Function: Get_Index
--  @Description:
--     Returns the minimum index of Item in A.
--  @Parameters:
--     +A: the array
--     +Item: element searched for
--  @Return:
--     The minimum index of Item in A.
--  @Pre:
--    true
--  @Post:
--     if exists 1 <= I <= UPPER_BOUND: A(I) = Item then
--       result = min {1 <= k <= UPPER_BOUND | a(j) = item }
--    else
--       result = 0

Answer 1

@Pre а также @Post теги должны документировать подход вашего модуля к проектированию по контракту. Как вы заметили, любое предварительное условие должно быть верным для успешного выполнения, а любое постусловие - это обещание, которое будет выполнено вашим кодом. @Error_Handling Тег определяет, как вы справляетесь с нарушениями двух других.

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

Накапливаются несколько преимуществ:

1. Программист API может четко заявить о предполагаемом поведении.
2. Клиент API может различать возможные источники ошибок.
3. Рецензент может проверить, соответствует ли намерение реализации.