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 标签应记录模块的 按合同设计。正如您所观察到的，任何 先决条件 必须为 true 才能成功执行，并且任何 postcondition 是您的代码要履行的承诺。 @Error_Handling 标记标识您如何处理其他两个标记的违规行为。

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

可以带来以下几个好处：

1. API 程序员可以清楚地说明预期的行为。
2. API 客户端可以区分可能的错误来源。
3. 审核者可以验证意图是否与实现相匹配。

另请参阅Ada 简介：按合约进行设计，它说明了 Ada 2012 对执行合同的支持。 Ada 2012 的基本原理 提供 主题和相关方面的概述 。