本课目标
完成本课后，你将能够：
-
掌握Ada注释的完整语法与文档化规范
-
使用AdaDoc工具生成专业API文档
-
应用代码布局、缩进、空行的最佳实践
-
配置编辑器实现自动格式化与风格检查
-
编写符合DO-178C等安全标准的高可读性代码
一、Ada注释机制详解
1.1 单行注释：唯一原生支持
Ada标准仅定义单行注释，以双连字符 -- 开头，延伸至行尾：
-- 这是完整的单行注释
X := 10; -- 行尾注释，解释赋值目的
-- 多行注释需要每行添加--
-- 这是第二行注释
-- 这是第三行注释
Y := 20;
关键特性：
| 特性 | 说明 | 示例 |
|---|---|---|
| 无嵌套问题 | 每行独立，不存在/* */嵌套混乱 | -- 内部 -- 还是注释 |
| 可位于任何位置 | 代码前后、行尾均可 | X := -- 中间注释！ 10; |
| 不跨行 | 必须每行以--开头 | 无多行块注释语法 |
| 标准统一 | 所有Ada编译器完全一致 | 无方言差异 |
1.2 注释的工业规范
有效注释 vs 无效注释：
-- 无效注释：重复代码显而易见的内容
X := X + 1; -- 将X加1
-- 有效注释：解释"为什么"而非"是什么"
X := X + 1; -- 补偿传感器零点漂移，经校准实验确定
-- 无效注释：过时或错误
-- 计算圆面积（实际代码已改为矩形）
Area := Width * Height;
-- 有效注释：与代码同步的意图说明
-- 计算矩形封装区域，用于缓冲区大小分配
Area := Width * Height;
注释黄金法则：
-
解释意图：为什么这样做，而非做了什么
-
记录假设：输入范围、边界条件、副作用
-
标记待办：
-- TODO: 优化算法复杂度 -
保持同步：修改代码必改注释
二、文档化注释：AdaDoc规范
2.1 标准文档注释格式
Ada社区采用结构化注释生成API文档，虽无官方标准，但GNATdoc工具广泛支持：
-- 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工具链提供）：
# 生成HTML文档
gnatdoc -P my_project.gpr --output-dir=docs/
# 生成文本摘要
gnatdoc -P my_project.gpr --format=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默认，可配置）：
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 垂直布局：空行与分组
逻辑分组原则：
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字符（传统终端宽度，便于并排查看）
对齐技巧：
-- 参数对齐：冒号对齐
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代码：
# 基本格式化（覆盖原文件前备份）
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）：
{
"[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配置：
Edit → Preferences → Editor → Ada → Indentation: 3
Edit → Preferences → Editor → Ada → Max line length: 100
五、安全关键领域的特殊规范
5.1 DO-178C编码标准
航空电子软件需遵循的强制规范：
-- 规则：每行单一声明或语句
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; |
六、完整风格示例：环形缓冲区
------------------------------------------------------------------------------
-- 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.格式修复：以下代码存在多处风格问题，找出并修正：
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编码安全规范
提示警告：本课程内容（包括但不限于文字、图片、音频、视频等）版权归原作者所有，未经授权严禁转载、复制、翻录、传播或以任何方式用于商业用途。本课程仅供个人学习使用，请尊重知识产权，共同维护良好的创作环境。如有疑问或需授权合作，请联系版权方。感谢您的理解与支持！
