Adaの機能ヘッダーのオプションのコメントセクション

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タグは、他の2つの違反をどのように処理するかを識別します。

具体的な例として、Arithmetic_Meanの実装では空の入力配列を無視して平均値0を返します。発生した例外を伝播します。これは文書化すべき行動です。

いくつかの利点が生ずる：

1. をAPIプログラマが意図した動作を明確に述べることができます。
2. APIクライアントは、考えられるエラーの原因を区別できます。
3. 査読者は、意図が実装と一致するかどうかを検証できます。