ApexDoc 文档化指南 | Apex 代码注释标准

1

Document Your Apex Code

第 220 页

同学们，咱们今天来聊聊一个能让你代码更清晰、团队协作更顺畅的好工具——ApexDoc。你可以把它理解成一种写注释的“标准格式”。就像我们平时写信有称呼、正文、落款一样，写代码的时候，如果在类、方法这些结构前面，用一套固定的方式来加注释，那不管是其他开发者，还是自动生成文档的工具，甚至现在很火的AI助手，都能一眼看懂你的代码是做什么的。这套格式其实是参考了Java里很成熟的JavDoc，然后针对咱们Salesforce的Apex语言做了专门的定制，加了很多特制的标签和规范。这样一来，代码的注释就不再只是“随口一说”，而是变得有章可循。为什么要花时间学这个呢？你想啊，一个项目久了，或者团队的人换了一拨，那些没有规范注释的代码，读起来就像看天书。但用了ApexDoc，大家就能快速上手，维护起来也省心。它就是为了促进协作、提高代码的长期可维护性而生的。我们今天这一部分内容，就会带着大家一步步看完，怎么给所有的Apex结构——不管是类、方法、还是属性——写上标准的ApexDoc注释。我们会学到它的整体结构、有哪些常用的标签，以及一些实践中的最佳做法。慢慢来，不难，学会了，你的代码就会像一本打开的书，人人都爱读。咱们开始吧。

查看详情

2

ApexDoc — Basic Comment Format

第 221 页

同学们，今天咱们来说说ApexDoc注释，这是Salesforce里用来给代码自动生成文档的一种特殊写法。它跟普通的Apex注释最大的区别就在开头：普通块注释是用斜杠加一个星号，也就是 `/*`，而ApexDoc注释呢，是斜杠加两个星号——`/，`。多了这一颗星，解析工具才知道“哦，这是文档注释，我得把它提取出来”。写的时候还有几条小规矩：这条注释要紧紧贴在它要说明的代码元素前面，比如类、接口、枚举、方法、构造器，或者属性声明的上方。如果注释内容不止一行，那么从第二行开始，每一行前面都要先写一个星号`*`，让它看起来整齐排列。你放心，生成文档的工具很聪明，它会自动忽略每行开头的那个星号和多余空格，只把里面的文字挑出来用。注释里的第一段文字就是主要描述，必须用一句简洁的总结开头，并且这句话要以句号结尾。在这句总结之后，你可以在同一个段落里继续写一些补充说明，提供更多上下文信息。简单总结就是：用`/，`开头、紧挨声明、续行加星号、第一句总结写完整并带句号。这样写出来的注释就能被ApexDoc工具正确识别，生成漂亮的文档啦。好了，这部分规则其实很直白，大家记住这几点就够了。

查看详情

3

ApexDoc — Block & Inline Tags

第 222 页

好，我们来看看这一页讲的是什么——Apex 里的文档注释标签，也就是我们写代码时用来生成文档的那些特殊标记。你想象一下，当你在写一个方法时，为了让别人（也包括未来的自己）能快速看懂这个方法干嘛用的、参数是什么、返回值是什么，你就可以用这些标签来“标注”一下。这些标签都以 `@` 开头，所以也叫“块标签”。首先，你得知道每个块标签都要单独占一行，放在方法描述之后。比如： - `@param`：用来描述方法的每一个参数。注意哦，有几个参数就得写几个 `@param`，而且顺序和名字必须严格跟你方法签名里的一致。 - `@return`：描述这个方法返回的是什么。 - `@throws`：描述可能抛出的异常。 - `@see`：用来做交叉引用，可以指向别的类、方法，或者一个文本说明，甚至一个 URL。说完块标签，还有一种叫“内联标签”。它们不是单独一行，而是藏在描述文字里，用花括号 `{}` 包起来。常见的有： - `{@code}`：把里面的文字格式化成代码样式。 - `{@link}`：创建一个可点击的内联链接，直接跳转到别的地方。 - `{@literal}`：就是原样显示文本，不会去解析里面的特殊字符。 - 还有一个 `{@hidden}`，它很特别，可以让这一行在最终生成的文档里不显示出来，相当于“隐藏”了。记起来很简单：块标签就是新起一行，说明参数、返回值啥的；内联标签就是嵌在描述里，做个小修饰或链接。这样你写出来的注释既规范，又能自动生成漂亮的文档。好了，这一页的核心就是这些。下次写方法注释的时候，你可以试着用起来，会发现代码的可读性直线上升。

查看详情

4

Documenting Classes & Interfaces

第 223 页

同学们，今天我们来聊聊在Apex开发中一个经常被忽略，但又极其重要的环节——给我们的类和接口写注释文档。你可能会想，“代码写对了不就行了，干嘛还要费劲写注释？” 嗯，这就是我要告诉你的：好的文档就像一部电器清晰的使用说明书，能让别人（包括几个月后的你自己）不用拆开整台机器，就立刻明白它能做什么、怎么用、以及该注意什么。我们先说，记录一个类，。当你写完一个类，应该立刻在代码最上面写一段清晰的概述，回答三个问题：这个类的，目的，是什么？它承担了哪些，职责，？以及它有哪些，关键特征，？比如，它是一个用来处理数据校验的工具类，还是管理HTTP请求的服务类？它会不会自动重试失败的操作？把这些交代清楚，别人一眼就知道这个类的定位。紧接着，用一个，总结句，把这个类的总体目标直白地讲出来。也就是一句话说清楚——这个类在系统里扮演什么角色，为什么它存在。如果这个类用了某种不太直观的设计模式，比如单例模式或工厂模式，你还要简单解释一下，为什么要用这种共享方式，，避免别人疑惑“这里怎么这样写？” 再来看，接口，。如果说类是一个成品的电器，那么接口就是一纸合同。你在文档里要写清楚这份“合同”允许其他类，做什么，，而绝对不要去限定“怎么做”。实现细节是属于实现类自己的事。你要让看文档的人明白：“只要实现了这个接口，我就可以调用这些能力，放心依赖这些行为。” 所以，针对接口里的每一个方法声明，你都要记录清楚： - ，预期的行为，是什么（它会发生什么，有什么副作用）， - 每个，参数，代表什么，有没有特殊限制， - 以及，返回值，的含义，什么情况下返回什么。这份文档其实就是在给所有将来想要实现这个接口的类画一条跑道——它告诉这些类：你只要跑在这条跑道上，按照我描述的行为来，任何使用你的代码就都能正常工作。这就是文档的强大之处：，设定清晰的期望，。所以，同学们，从现在开始，养成写高质量注释的习惯吧。它会让你的代码从“只有你和上帝懂”，变成“整个团队都能愉快协作”。记住，好的文档，就是最好的沟通。

查看详情

5

Documenting Enums, Methods & Constructors

第 224 页

同学们，咱们今天来看一下怎么给枚举类型写文档，这可是个好习惯，能让代码更易懂、更专业。首先回忆一下，什么是枚举？在Apex里，枚举是一种抽象数据类型，它定义了一组有限的、有名字的常量值。比如说，你可以定义一个季节的枚举，包含“春、夏、秋、冬”，或者订单状态“新建、已发货、已完成”。这些值都是固定的，不能随便改。那么，我们在写枚举的时候，一定要把文档写清楚。第一，要记录这个枚举的用途。它是用来干什么的？是表示订单状态？还是日志级别？让别人一看就明白这个枚举存在的意义。第二，对于里面定义的每一个常量，如果名字不是一目了然的，就需要澄清。比如有个常量叫“P”，别人根本猜不出是“Pending”还是“Processed”，那你就得在文档里解释一下它到底代表什么。如果名字本身就很直白，像“SUCCESS”，那就不用额外说明了。重点来了：在枚举里，方法和构造函数的文档是重中之重。因为它们直接关系到别人怎么使用你的代码。对于这些方法，我们要规范地使用文档标签。对于每一个参数，都要用 @param 来标记，而且顺序和名字必须和方法签名里完全一致。在描述这个参数的时候，你要讲清楚三点：类型期望、空约束和有效格式。比如，可以这样写：“@param recordId 要处理的记录ID，类型为Id，不能为null，必须是15位或18位的有效ID。”这下调用者就知道，你不能传个空值，也不能传个乱七八糟的字符串。对于返回值，要用 @return 。描述里要指定什么情况下会返回null，以及返回的数据结构。比如：“@return 返回一个List<Contact>，如果找不到对应联系人则返回null。”这样别人就知道要做判空处理，也知道拿到的数据类型。还有，如果方法可能抛出异常，一定要用 @throws 把重要的异常列出来。比如参数校验失败会抛 IllegalArgumentException，或者DML失败会抛 DmlException，都得写清楚。这样调用者才能提前准备try-catch，代码才更健壮。总结一下，给枚举写好文档，就是让它的用途、常量、方法和异常都透明。养成这些习惯，你们写出的代码就像自带说明书，队友接手时都会感谢你的。好了，这个要点咱们就说这么多，接下来看个实际例子。

查看详情

6

Documenting Properties, Triggers & Annotations

第 225 页

同学们，咱们今天来聊聊怎么把Apex代码的“公共API”文档写清楚，这件事看起来基础，但对团队协作和长期维护特别重要。咱们先想一下，一个类的公共API到底由什么构成？其实就是那些用，public，或，global，声明的属性、成员变量和方法。换句话说，只要外面的人能访问到的，都属于公共API。那在记录这些属性的时候，一定要讲清楚三件事：第一是它的，用途，，也就是这个属性到底是干什么的；第二是它的，数据类型，，比如是String、Integer还是自定义对象；第三是，使用说明，，比如有没有默认值、会不会自动改变、存取时有什么限制等等。举个例子，如果一个计数器变量 counter 是 public Integer，文档里就不能只写“计数器”，而要说明“记录当前已处理的记录数，会在每次调用后自增，请不要手动修改”。这样别人一看就心里有数了。接下来要特别注意触发器。我们一直强调，不要直接在触发器里堆业务逻辑，那样既难测试也不容易复用。正确的做法是把逻辑委托给专门的，处理程序类，，也就是Handler类。那么写ApexDoc文档时，这个触发器上要记得加上一些标准的标记，尤其是，@since，，用来标明这个触发器是从哪个版本开始引入的，跟软件的迭代步调保持一致。再往下，就是各种注解了。注解不仅是给编译器看的提示，更是给后面接手代码的人看的说明书，所以注释里必须把它们的含义和场景讲明白。 - ，@AuraEnabled，：这是让 Lightning 组件能调用这个方法。写注释时一定要说明是否启用了缓存，也就是，cacheable=true，的设置，因为开启缓存后数据可能不实时，必须让调用方清楚这一点。 - ，@InvocableMethod，：这是给流（Flow）或过程构建器用的。

查看详情

7

ApexDoc Complete Examples

第 226 页

同学，今天我们来看一下怎么给咱们的Apex代码写一份漂亮的“说明书”，也就是ApexDoc注释。你可别小看它，有了这些注释，不仅别人能一眼看懂你的代码，以后还能用工具自动生成整洁的文档，就像 Salesforce 官方文档那样。咱们举个简单的例子，假如你写了一个叫 `AccountService` 的类，专门用来处理客户相关的逻辑。那怎么给它加上ApexDoc呢？首先，在类的最上面，我们会写一个“总介绍”，这叫，类级注释，。你要用简洁的话说明这个类是干嘛的，它用的是什么共享模式，是“有共享”还是“无共享”。因为共享模式会影响数据安全，所以一定要写清楚。然后，你还可以打上各种小标签，比如 `@author` 写上作者大名，`@since` 说明是从哪个版本开始有的，`@version` 标个版本号。如果想让人去参考别的地方，就用 `@see` 指一下。如果想要把类归类，可以用 `@group`。如果还能贴上一段使用的小例子，就放在 `@example` 标签里，并且用 `{@code ...}` 把代码包起来，这样格式不会乱。说完类，我们再往下看方法。每个方法也应该有自己的注释。在方法前面，你先描述它要完成什么任务，然后一个个介绍它的参数：用 `@param` 把每个参数的名字、类型和作用讲清楚，就像说明书里的零件清单。接着，用 `@return` 告诉别人这个方法会返回个什么东西，是什么类型的，代表什么含义。如果方法可能会抛出异常，千万别忘了用 `@throws` 列出来，并说明在什么情况下会抛出，这样别人才知道怎么预防。有时候方法里还能带一个完整的使用示例，这时就在方法注释的最后加上 `@example`，同样用 `{@code}` 把代码段包起来，别人一看就知道怎么调用。还有一点特别重要：如果哪天你觉得某个方法过时了，不推荐大家继续用，千万别偷懒直接删掉，而是要用 `@deprecated` 标签。同时，你还可以配合 `{@link 新方法名}` 来指路，告诉大家“别用这个了，快去用那个新的”。这样既保证了老代码不报错，又引导大家往新方案迁移，非常贴心。简单说，ApexDoc 就像给代码穿上一件标准制服，让人一眼就能看出职责、参数、异常和示范。以后你写任何工具类、服务类，养成这个习惯，你的代码可维护性会大大提高，团队协作也会顺畅很多。好了，这一页咱们就讲到这儿。你可以试着动手给自己之前写的类加上这样的注释，感受一下有多清爽。有什么疑问随时问我。

查看详情

DEX455

课程介绍

课程章节

Document Your Apex Code

ApexDoc — Basic Comment Format

ApexDoc — Block & Inline Tags

Documenting Classes & Interfaces

Documenting Enums, Methods & Constructors

Documenting Properties, Triggers & Annotations

ApexDoc Complete Examples

📋 课程信息

🔗 相关链接