function - Ada 函数头中的可选注释部分

Question

当读者开始阅读函数代码时，他应该已经非常清楚它是做什么的，它是如何做的，以及他可能会遇到什么问题。我正在尝试编写易于理解的干净、结构化、注释良好的代码。我正在阅读 Ada Style Guide 和一些我不太了解的东西，我可以为可选部分写什么 (例如:@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标签应该记录你的模块对Design by Contract的方法.正如您所观察到的，任何 precondition必须为 true 才能成功执行，并且任何 postcondition是由您的代码实现的 promise 。 @Error_Handling标签标识您如何处理违反其他两项的行为。

作为一个具体的例子，你的 Arithmetic_Mean 的实现默默地忽略一个空输入数组，返回均值为零；它传播引发的任何异常。这些是应该记录的行为。

有几个好处:

API 程序员可以清楚地说明预期的行为。

API 客户端可以区分可能的错误来源。

审阅者可以验证意图是否与实现相匹配。

另见 Introduction to Ada: Design by contracts ，它说明了 Ada 2012 对执行契约(Contract)的支持。 Rationale for Ada 2012提供 overview主题和 related aspects .