第6课｜注释与代码风格

本课目标

完成本课后，你将能够：

掌握Ada注释的完整语法与文档化规范
使用AdaDoc工具生成专业API文档
应用代码布局、缩进、空行的最佳实践
配置编辑器实现自动格式化与风格检查
编写符合DO-178C等安全标准的高可读性代码

一、Ada注释机制详解

1.1 单行注释：唯一原生支持

Ada标准仅定义单行注释 ，以双连字符 -- 开头，延伸至行尾：

ada 复制代码

-- 这是完整的单行注释
X := 10;  -- 行尾注释，解释赋值目的

-- 多行注释需要每行添加--
-- 这是第二行注释
-- 这是第三行注释
Y := 20;

关键特性：

特性	说明	示例
无嵌套问题	每行独立，不存在`/* */`嵌套混乱	`-- 内部 -- 还是注释`
可位于任何位置	代码前后、行尾均可	`X := -- 中间注释！ 10;`
不跨行	必须每行以`--`开头	无多行块注释语法
标准统一	所有Ada编译器完全一致	无方言差异

1.2 注释的工业规范

有效注释 vs 无效注释：

ada 复制代码

-- 无效注释：重复代码显而易见的内容
X := X + 1;  -- 将X加1

-- 有效注释：解释"为什么"而非"是什么"
X := X + 1;  -- 补偿传感器零点漂移，经校准实验确定

-- 无效注释：过时或错误
-- 计算圆面积（实际代码已改为矩形）
Area := Width * Height;

-- 有效注释：与代码同步的意图说明
-- 计算矩形封装区域，用于缓冲区大小分配
Area := Width * Height;

注释黄金法则：

解释意图：为什么这样做，而非做了什么
记录假设：输入范围、边界条件、副作用
标记待办 ： -- TODO: 优化算法复杂度
保持同步：修改代码必改注释

二、文档化注释：AdaDoc规范

2.1 标准文档注释格式

Ada社区采用结构化注释生成API文档，虽无官方标准，但GNATdoc工具广泛支持：

ada 复制代码

--  package Math_Utils
--  ---------------
--
--  Description:
--    提供基础数学运算工具，针对嵌入式系统优化
--
--  Usage:
--    with Math_Utils;
--
--  Author:
--    John Doe <john@example.com>
--
--  Version:
--    1.2.0
--
--  License:
--    MIT License

package Math_Utils is

   --  function Factorial
   --  ------------------
   --
   --  Description:
   --    计算非负整数的阶乘
   --
   --  Parameters:
   --    N - 输入值，必须满足 0 <= N <= 12
   --
   --  Returns:
   --    N的阶乘，若N > 12则返回0（溢出保护）
   --
   --  Raises:
   --    Constraint_Error - 当N < 0时
   --
   --  Example:
   --    F := Factorial (5);  -- F = 120
   --
   --  See Also:
   --    Combinations, Permutations

   function Factorial (N : Natural) return Natural
      with Pre => N <= 12,
           Post => (if N <= 12 then Factorial'Result <= 479_001_600);

   --  procedure Swap
   --  --------------
   --
   --  Description:
   --    交换两个同类型变量的值
   --
   --  Parameters:
   --    A - 第一个变量，将被赋予B的原始值
   --    B - 第二个变量，将被赋予A的原始值

   generic
      type Element is private;
   procedure Swap (A, B : in out Element);

end Math_Utils;

2.2 文档注释元素速查

标签	用途	位置
`Description`	功能概述	所有单元
`Parameters`	参数说明（名-描述对）	子程序
`Returns`	返回值说明	函数
`Raises`	可能抛出的异常	子程序
`Precondition`	前置条件（Ada 2012可用契约替代）	子程序
`Postcondition`	后置条件	子程序
`Example`	使用示例	所有单元
`See Also`	相关引用	所有单元
`Author`	作者信息	包/库单元
`Version`	版本号	包/库单元
`License`	许可证	包/库单元
`Note`	特殊说明	所有单元
`Warning`	使用警告	所有单元

2.3 使用GNATdoc生成文档

安装GNATdoc（随GNAT工具链提供）：

bash 复制代码

# 生成HTML文档
gnatdoc -P my_project.gpr --output-dir=docs/

# 生成文本摘要
gnatdoc -P my_project.gpr --format=text

输出示例：

text 复制代码

Package Math_Utils
  [package spec math_utils.ads:1]
  Description: 提供基础数学运算工具，针对嵌入式系统优化
  
  function Factorial (N : Natural) return Natural
    [math_utils.ads:25]
    Description: 计算非负整数的阶乘
    Pre: N <= 12
    Post: Factorial'Result <= 479_001_600

三、代码布局与格式

3.1 缩进规范

标准缩进：3个空格（GNAT默认，可配置）：

ada 复制代码

procedure Indentation_Example is
   -- 第1级缩进（3空格）
   
   procedure Nested is
      -- 第2级缩进（6空格）
      
      if Condition then
         -- 第3级缩进（9空格）
         Do_Something;
      end if;
      
   end Nested;
   
begin
   -- 回到第1级
   null;
end Indentation_Example;

缩进规则：

结构	缩进行为
`is` / `begin` / `loop`	后续内容缩进一级
`if` / `then` / `else`	`then`后内容缩进，`else`与`if`对齐
`case` / `when`	`when`与`case`对齐，箭头后内容缩进
`exception`	与对应`begin`对齐
`end`	与对应开启关键字对齐

3.2 垂直布局：空行与分组

逻辑分组原则：

ada 复制代码

package Layout_Example is

   ---------------------------------------------------------------------------
   --  类型声明
   ---------------------------------------------------------------------------
   
   type Status is (OK, Warning, Error, Critical);
   type Priority is range 1 .. 10;
   
   
   ---------------------------------------------------------------------------
   --  常量定义
   ---------------------------------------------------------------------------
   
   Default_Priority : constant Priority := 5;
   Max_Retries      : constant := 3;
   
   
   ---------------------------------------------------------------------------
   --  子程序声明
   ---------------------------------------------------------------------------
   
   -- 初始化子系统
   procedure Initialize
      with Post => Is_Initialized;
      
   -- 检查初始化状态
   function Is_Initialized return Boolean;
   
   -- 处理任务
   procedure Process 
      (Data     : in out Data_Type;
       Priority : in     Priority := Default_Priority)
      with Pre => Is_Initialized;
      
      
   ---------------------------------------------------------------------------
   --  异常定义
   ---------------------------------------------------------------------------
   
   Initialization_Error : exception;
   Processing_Error     : exception;

end Layout_Example;

空行使用指南：

场景	空行数	目的
不同声明类别间	2行	视觉分隔
相关子程序间	1行	逻辑分组
注释块前后	1行	突出说明
长过程内部分段	1行	步骤划分

3.3 水平布局：行长与对齐

行长限制：80或100字符（传统终端宽度，便于并排查看）

对齐技巧：

ada 复制代码

-- 参数对齐：冒号对齐
procedure Process_Data
  (Input_Buffer  : in     Data_Array;   -- 输入数据
   Output_Buffer :    out Data_Array;   -- 处理结果
   Actual_Length :    out Natural;      -- 实际处理长度
   Options       : in     Process_Options := Default_Options);

-- 赋值对齐：赋值符对齐
Max_Size     : constant := 1024;
Buffer_Size  : constant := Max_Size * 2;
Header_Size  : constant := 16;
Total_Size   : constant := Buffer_Size + Header_Size;

-- 枚举对齐：等号对齐
type Error_Code is
  (No_Error        = 0,
   Invalid_Argument = 1,
   Out_Of_Memory    = 2,
   IO_Error         = 3);

四、代码风格自动化工具

4.1 GNAT格式工具：gnatpp

gnatpp（GNAT Pretty Printer）自动格式化Ada代码：

bash 复制代码

# 基本格式化（覆盖原文件前备份）
gnatpp -P my_project.gpr --output-dir=formatted/

# 指定缩进宽度
gnatpp --indentation=3 --indent-continuation=2 *.adb

# 保留原有布局（仅修正明显错误）
gnatpp --preserve-blank-lines *.ads

常用选项：

选项	说明	推荐值
`--indentation=N`	基本缩进空格数	3
`--indent-continuation=N`	续行缩进	2
`--max-line-length=N`	最大行长度	80或100
`--preserve-blank-lines`	保留原有空行	是
`--align-modes`	对齐in/out/in out	是
`--name-case-as-declared`	标识符大小写与声明一致	是

4.2 集成到编辑器

VS Code配置（settings.json）：

json 复制代码

{
    "[ada]": {
        "editor.tabSize": 3,
        "editor.insertSpaces": true,
        "editor.rulers": [80, 100],
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "AdaCore.ada"
    },
    "ada.gnatpp.args": [
        "--indentation=3",
        "--max-line-length=100",
        "--align-modes"
    ]
}

GPS/GNATstudio配置：

text 复制代码

Edit → Preferences → Editor → Ada → Indentation: 3
Edit → Preferences → Editor → Ada → Max line length: 100

五、安全关键领域的特殊规范

5.1 DO-178C编码标准

航空电子软件需遵循的强制规范：

ada 复制代码

-- 规则：每行单一声明或语句
X := 10; Y := 20;  -- 非法：多语句同行

-- 规则：所有控制结构必须完整
if Condition then
   Do_Something;
end if;  -- 必须显式结束，不能省略

-- 规则：所有路径必须有明确行为
if X > 0 then
   Positive_Case;
else
   -- 必须处理else，即使为空
   null;
end if;

-- 规则：禁用风险特性
-- 禁止使用goto（除非跳转到异常处理器）
-- 禁止使用地址算术（除非硬件接口）
-- 禁止使用未初始化变量

5.2 MISRA Ada规则示例

规则ID	描述	示例
MISRA-Ada-001	避免隐式类型转换	`X := Integer (Y);` -- 必须显式转换
MISRA-Ada-002	循环必须有静态边界	`for I in 1 .. 10 loop` -- 范围必须编译期确定
MISRA-Ada-003	禁止动态内存分配	禁用`new`，使用静态数组或池分配
MISRA-Ada-004	所有函数必须有单一返回点	避免多个`return`语句
MISRA-Ada-005	异常处理器必须记录	`when E : others => Log (E); raise;`

六、完整风格示例：环形缓冲区

ada 复制代码

------------------------------------------------------------------------------
--                              Ring_Buffer                                 --
--                                                                          --
--                         A Generic Circular Buffer                        --
--                                                                          --
--  Copyright (c) 2024 Example Corp. All Rights Reserved.                   --
--  SPDX-License-Identifier: MIT                                            --
------------------------------------------------------------------------------

generic
   type Element_Type is private;
   Capacity : Positive;
   -- 缓冲区容量，必须为正数

package Ring_Buffer is

   pragma Pure;  -- 声明为纯包，无副作用

   ---------------------------------------------------------------------------
   --  类型与常量
   ---------------------------------------------------------------------------

   subtype Count_Type is Natural range 0 .. Capacity;
   -- 当前元素数量类型

   Buffer_Full  : exception;
   Buffer_Empty : exception;

   ---------------------------------------------------------------------------
   --  类型定义
   ---------------------------------------------------------------------------

   type Buffer_Type is private;
   -- 环形缓冲区私有类型

   ---------------------------------------------------------------------------
   --  构造函数
   ---------------------------------------------------------------------------

   function Create return Buffer_Type
      with Post => Count (Create'Result) = 0;
   -- 创建空缓冲区

   ---------------------------------------------------------------------------
   --  查询操作
   ---------------------------------------------------------------------------

   function Count (Buffer : Buffer_Type) return Count_Type;
   -- 返回当前元素数量

   function Is_Empty (Buffer : Buffer_Type) return Boolean
      is (Count (Buffer) = 0);
   -- 检查是否为空

   function Is_Full (Buffer : Buffer_Type) return Boolean
      is (Count (Buffer) = Capacity);
   -- 检查是否已满

   ---------------------------------------------------------------------------
   --  修改操作
   ---------------------------------------------------------------------------

   procedure Push
      (Buffer : in out Buffer_Type;
       Item   : in     Element_Type)
      with Pre  => not Is_Full (Buffer) or else raise Buffer_Full,
           Post => Count (Buffer) = Count (Buffer'Old) + 1;
   -- 添加元素到尾部，满时抛出Buffer_Full

   procedure Pop
      (Buffer : in out Buffer_Type;
       Item   :    out Element_Type)
      with Pre  => not Is_Empty (Buffer) or else raise Buffer_Empty,
           Post => Count (Buffer) = Count (Buffer'Old) - 1;
   -- 移除头部元素，空时抛出Buffer_Empty

   procedure Clear (Buffer : in out Buffer_Type)
      with Post => Is_Empty (Buffer);
   -- 清空缓冲区

private

   ---------------------------------------------------------------------------
   --  私有实现
   ---------------------------------------------------------------------------

   type Element_Array is array (Positive range <>) of Element_Type;

   type Buffer_Type is record
      Data  : Element_Array (1 .. Capacity);
      Head  : Positive range 1 .. Capacity := 1;
      Tail  : Positive range 1 .. Capacity := 1;
      Count : Count_Type := 0;
   end record;

end Ring_Buffer;

七、本课总结

Ada仅支持单行注释 -- ，多行需每行添加，避免嵌套混乱
结构化文档注释（Description/Parameters/Returns等）支持自动生成API文档
标准缩进3空格，80/100字符行宽，逻辑分组用空行分隔
gnatpp 自动格式化代码，gnatcheck验证风格规范
DO-178C/MISRA Ada对安全关键代码有严格格式与结构要求

八、课后练习

1.注释改进：为第5课的 Employee_Manager 包添加完整文档注释。

2.格式修复：以下代码存在多处风格问题，找出并修正：

ada 复制代码

procedure bad(X:integer;y:IN OUT integer)IS
begin
if x>0 then y:=x;else y:=-x;end if;end bad;

3.gnatpp实践：对本课示例运行 gnatpp ，对比前后差异。

4.文档生成：使用 gnatdoc 为前几课项目生成HTML文档。

5.MISRA检查：查阅MISRA Ada规范，列出5条本课程代码已遵守的规则。

九、下节预告

第7课｜基本语法元素

我们将：

系统学习Ada的字符集、词法单元与分隔符
掌握数值字面量的多种表示形式（十进制、十六进制、科学计数法）
理解字符串字面量与宽字符支持
学习编译指示（pragma）的基础用法

关键术语表

结构化注释：包含特定标签（Description/Parameters等）的文档化注释

GNATdoc：从Ada源代码提取文档生成HTML/文本的工具

gnatpp：GNAT代码格式化工具（Pretty Printer）

DO-178C：航空电子软件适航标准，规定严格编码规范

MISRA Ada：汽车与嵌入式系统的Ada编码安全规范

提示警告：本课程内容（包括但不限于文字、图片、音频、视频等）版权归原作者所有，未经授权严禁转载、复制、翻录、传播或以任何方式用于商业用途。本课程仅供个人学习使用，请尊重知识产权，共同维护良好的创作环境。如有疑问或需授权合作，请联系版权方。感谢您的理解与支持！