[iOS-Objective-C] 注释

Cocoa 开发者间流传着一句格言，Objective-C 的冗长使得其代码就是有效的自我说明。有了[longMethodNamesWithNamedParameters:]以及参数的显式类型，Objective-C 的方法不会给人留下太多的想象空间。但即使是自我说明的代码也可以通过注释加以改进。那么 Objective-C 中的注释具体应该怎么写呢，总结起来说就是，不要写不该写的注释，不要省不该省的注释。

不该写的注释

• 注释不应当解释代码在做什么，而是应该解释这段代码为什么要这样做。大多数情况下，解释每一步代码在做什么的注释是没有意义的，通过良好的编码规范和定义，变量名和方法名本身就可以是一种逻辑的解释，阅读者完全可以通过直接阅读代码知道这段代码做了什么，而解释只是简单的翻译了代码，重复了阅读者已经知道的内容，其实反而是增加了阅读者的阅读时间。
• 被弃用的代码应该被删掉，这些代码会非常影响阅读，而且它们一般又很长。 在绝大多数情况下，被弃用的代码不会重新派上用场，即使出现了少数情况，你也可以从版本控制系统中找到它们

不该省的注释

• 在业务代码中，只有当非常必要的情况下，才应该添加注释，而且应当言简意赅。比如有一段逻辑复杂的代码，通过阅读代码无法快速直接的了解其作用时，应当添加简明的注释。
• 在上述不该写的注释中指出，对于代码执行步骤的解释型注释是冗余的，但如果一个类中的某一功能方法调用链很长时，可以在入口方法处写一些简明的注释，说明整个操作做了什么工作，这类注释可以对整个类的功能块进行划分，使阅读者可以快速有整体的了解，而具体的实现，则通过方法名和代码逻辑说明。
• 还有一类注释是接口注释，就是把要暴露出来的元素都写上详细的注释，一般用于供别人使用的框架或类库，这种注释的作用是让使用者在不需要看源码或无法看到源码的情况下，可以根据注释来使用。另外，这类注释一般可以被工具生成为文档。

在 Objective-C 中写注释

对复杂逻辑的解释备注，使用简单的单行注释即可。对于接口注释，从 Xcode8 开始，苹果已将插件VVDocumenter的功能集成进 Xcode 中，可通过快捷键 command + alt + / 快速生成注释模板。而且这类模板对 appledoc 的支持很好，可能只需要很小的改动，比如枚举的注释格式等。