ApexDoc Complete Examples

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