Question

当读者开始阅读功能代码时，他应该已经非常了解它的作用，它是如何做到的，以及他可能遇到的问题。我正在尝试编写易于理解的干净，结构化，评论良好的代码。我正在阅读Ada Style Guide和一些我不太了解的事情，我可以为可选部分编写什么（对于exapmle：@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必须为成功执行才是真的，任何postcondition都是您的代码要履行的承诺。 @Error_Handling标记用于标识您如何处理其他两个违规行为。

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

积累了好处：

API程序员可以清楚地说明预期的行为。
API客户端可以区分可能的错误来源。
审核人可以验证意图是否与实施相符。

另请参阅Introduction to Ada: Design by contracts，其中说明了Ada 2012对执行合同的支持。 Rationale for Ada 2012提供了overview主题和related aspects。

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

1 个答案: