最全最详细的注释使用说明

作者: 外星听众 | 来源:发表于2019-01-08 17:47 被阅读16次

最全最详细的注释使用说明

[TOC]

前言

好的代码本身就是一种注释
代码的可读性更重要

注释的作用

代码的意义，除了完成功能业务这一最基本的要求之外，最终还要让别人能够读懂你的代码，让别人看得懂这段逻辑的意义，让别人更快更准确的理解这个方法的使用规则，同时使代码层级分明，方便快速浏览，以及生成使用文档等等。总之就是方便自己与他人后期维护。尤其是多人维护同一个项目的时候，注释的意义不言而喻，注释到位，别人去维护你写的代码时，就不会那么频繁的问你，甚至背后问候你了~~~

常用的注释分类

个人理解，对于注释的分类，从宏观功能上划分，可以分为代码注释和特殊功能注释。
代码注释又可以从位置特点上细分，可以分为单行注释，行尾注释（多用于属性、枚举值），多行注释（方法，协议，类等）。
下面我将从刚刚说的几个维度去介绍。

环境介绍

demo日期：2019.1.1
macOS 10.14.1
Xcode 10.1
示例代码语言：Objective-C

代码注释

需要写代码注释的地方非常多，包括不限于以下场景：文件的注释、类的注释、一段代码逻辑的说明；属性、枚举、方法、block等声明的注释

单行注释

最常见的就是这下面这样样式：

示例代码：

/* 这个方法的功能是做这个事情的，要注意呀~ */
+ (void)method {
    // 这里逻辑是这样的，要注意呀~
    [self new];
}

/// 单行注释10
@property (nonatomic, copy) NSString *str10;
//! 单行注释11
@property (nonatomic, copy) NSString *str11;
/** 单行注释12-可用于多行 */
@property (nonatomic, copy) NSString *str12;
/*! 单行注释13-可用于多行 */
@property (nonatomic, copy) NSString *str13;

上面两种注释方法，都是最最常见的普通注释的写法，两种写法但凡是写注释的地方都能用上，能够满足注释最基本的提示功能，没有什么特别要说明的。不过有一个缺陷是不会有 [option + 单击] 时Xcode的注释提示，所以和下面的单行注释分开说。

使用场景大多是代码块中，对于一些逻辑关键的的描述。另外，个人比较喜欢前后都加上一个空格的写法。

后面四种写法无论是否加空格，使用上都没有区别，都会有Xcode补全时的提示，以及 [option + 单击] 时的提示。

总之，单行注释适合无入参逻辑简单的类、方法、block 等的注释。
也可以用于属性或枚举的注释，不过，属性枚举注释个人认为更适合用行尾注释。

行尾注释

行尾最大的特点，就是在三个注释符号加上一个<小于号紧密的凑在一起。

示例代码：

@property (nonatomic, copy) NSString *str20; ///< 行尾注释20
@property (nonatomic, copy) NSString *str21; //!< 行尾注释21
@property (nonatomic, copy) NSString *str22; /**< 行尾注释22 */
@property (nonatomic, copy) NSString *str23; /*!< 行尾注释23 */

个人觉得行尾注释使用场景最多在于属性的声明和枚举值定义，这时候这么写一行就展示的下，屏幕大的时候看代码清晰明了。

有几个注意点（对于属性和枚举）：

所有上述写法，无论是否带空格，无论是在.h或.m中，Xcode代码补全时会有提示
在.h中，四种写法都能 [option + 单击] 显示方法注释
在.m中，只有 [///<不带空格] 这种注释写法点击才会显示注释

也就是说，[///<不带空格] 这种注释写法是最简单有效的行尾注释写法。不过，我总觉得不带空格总是不够优雅~

行尾注释不能适用于单行注释，否则和最最普通的注释无差别。

另外，如果属性含义过于复杂，尤其是存在多种状态时，可以使用多行注释的写法。

多行注释

示例代码：

手动写的样式：

/**
 *  方法注释test02
 */
- (void)test02 {}
/*!
 *  方法注释test03
 */
- (void)test03 {}

Xcode生成的样式：

/**
 这是一个多参数的方法
 
 @param count   参数0，数量
 @param str     参数1，字符串
 @param objc    参数2，对象
 @return        返回值，返回值bool情况说明
 */
- (BOOL)testC0WithCount:(NSUInteger)count str:(NSString *)str objc:(id)objc {
    return YES;
}

效果如图：

方法option提示-01.png

上面两种没有什么好说了，具体就是看个人喜好与团队风格了。下面说一下各个关键字的使用。

参数list：

注释中常用的标签：

关键字	说明
@brief	使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描述信息。
@discusstion	用它来写一段详尽的描述。如果需要你可以添加换行。
@param	通过它你可以描述一个 method 或 function的参数信息。你可以使用多个这种标签。
@return	用它来制定一个 method 或 function的返回值。
@note	注意点，补充说明
@see	用它来指明其他相关的 method 或 function。你可以使用多个这种标签。
@sa	同上
@code	使用这个标签，你可以在文档当中嵌入代码段。当在Help Inspector当中查看文档时，代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。
@remark	在写文档时，用它来强调任何关于代码的特殊之处。


/**
 *  各种关键字的使用示例

 @brief 使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描述信息。
 @discusstion 参数用它来写一段详尽的描述。如果需要你可以添加换行。
 我换两行试试
 第三行呢？
 
 
 @param str 参数
 @return        返回值，返回值bool情况说明

 @note 注意点，补充说明

 @see - (BOOL)testC0WithCount:(NSUInteger)count str:(NSString *)str objc:(id)objc{}
 @sa 同上

 @code
    使用这个标签，你可以在文档当中嵌入代码段。当在Help Inspector当中查看文档时，代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用标签
    // 方法
     - (void)testb0 {
        NSLog(@"注释标签");
     }
 @endcode
 
 @remark 在写文档时，用它来强调任何关于代码的特殊之处。
 
 *  其他注释
 */
- (BOOL)testC1WithParam:(NSString *)str {
    return NO;
}

效果如图：

方法option提示-02.png

附加：

记录文件常用标签：

关键字	说明
@file	使用这个标签来指出你正在记录一个文件（header 文件或不是）。如果你将使用Doxygen来输出文档，那么你最好在这个标签后面紧接着写上文件名字。它是一个top level 标签。
@header	跟上面的类似，但是是在 HeaderDoc中使用。当你不使用 Doxygen时，不要使用上面的标签。
@author	用它来写下这个文件的创建者信息
@copyright	添加版权信息
@version	用它来写下这个文件的当前版本。如果在工程生命周期中版本信息有影响时这会很重要。
@class	用它来指定一个class的注释文档块的开头。它是一个top level标签，在它后面应该给出class名字
@interface	同上
@protocol	同上两个一样，只是针对protocols
@superclass	当前class的superclass
@classdesign	用这个标签来指出你为当前class使用的任何特殊设计模式（例如，你可以提到这个class是不是单例模式或者类似其它的模式）。
@coclass	与当前class合作的另外一个class的名字。
@helps	当前class帮助的class的名字。
@helper	帮助当前class的class名字。

特殊功能注释

特殊功能注释展示效果通常都是在类的方法list中，也就是 [ctrl + 6] 快捷键显示的方法列表。

Pragma mark

这个通常用于一类方法的归纳

示例代码：

#pragma mark - Life Cycle
- (void)viewDidLoad {
    [super viewDidLoad];
}

#pragma mark - Delegate
#pragma mark UITableViewDataSource
- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
    return 0;
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    return nil;
}

#pragma mark UITableViewDelegate
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
    
}

#pragma mark - Event Response

#pragma mark - Getters UI

效果如图：

方法列表-01.png

可以看到，通过 pragma mark 使用，可以让方法分门别类，快速定位。

使用的注意点:

pragma mark 和 pragma mark - 都算是关键匹配对象，不可少打或改变大小写，
对于pragma mark，mark后面只要不是字母，就都可以正常识别。
对于pragma mark - ，中划线前后都一定有空格，在代码列表中，会在其文字描述的上方显示一个分割线

注释标签

标签的功能类似于Pragma mark，会在类的方法列表中展示对应的提示文案和特定icon，支持的有以下几种注释标签。

MARK: 文本内容，等同于#pragma mark
TODO: 文本内容，等待实现的功能
FIXME: 文本内容，需要修正的功能
!!!: 文本内容，需要改进的功能
???: 文本内容，有疑问的功能

代码示例：

/**
 *  *** 打印一句话我要用好多代码注释标签 ***
 *  MARK:   等同于#pragma mark
 *  TODO:   等待实现的功能
 *  FIXME:  需要修正的功能
 *  !!!:    需要改进的功能
 *  ???:    有疑问的功能
 
 *  另外，可以加上特定前缀方便检索，效果依旧不变
 *  ET_TODO:   等待实现的功能
 */
NSLog(@"注释标签");

效果如图：

标记注释-01.png

说明点：

五种提示都是关键字符串匹配，大小写和冒号都不能错
基于上面一点，可以自定义特定前缀，方便检索（一堆TODO: !!!: 的项目还是很感人的）

这个可是说是本人最喜欢的功能了，尤其是在代码中要特别强调说明一些事情时。

warming

这个没有什么过多说的，其实在使用好各种标签后，完全没有必要使用warming去产生一个让人烦恼的黄色标志。

示例代码：

#warning 这里是代码warming
#warning code warming

效果如图：

warning-01.png

但是需要注意的一点是，warning对于中文支持是存在问题的，我测试发现所有中文都不展示，且第一个单词的首写字母一定会被大写展示。

attribute

__attribute__表示属性，是Clang（GNU C）提供的一种源码注释，
方便开发者向编译器表达诉求，一般以__attribute__(*)的方式出现在代码中。
为了方便使用，一些常用属性被定义成了宏，经常出现在系统头文件中。
比如NS_CLASS_AVAILABLE_IOS(9_0) 就是 __attribute__(availability(9.0)) 
这个属性的简单写法。
下面介绍一些可能会频繁使用到的属性

iOS-Foundation使用

attribute-iOSFoundation01.png

AFNetworking使用

attribute-AFN01.png

SDWebImage使用

attribute-SD01.png

对于中attribute函数属性

函数属性(Function Attribute)
- noreturn
- noinline
- always_inline
- pure
- const
- nothrow
- sentinel
- format
- format_arg
- no_instrument_function
- section
- constructor
- destructor
- used
- unused
- deprecated
- weak
- malloc
- alias
- warn_unused_result
- nonnull
类型属性(Type Attributes)
- aligned
- packed
- transparent_union,
- unused,
- deprecated
- may_alias
变量属性(Variable Attribute)
- aligned
- packed
Clang特有的
- availability
- overloadable

高级应用-生成注解

ET_TODO:下期

注释的使用

主要使用快捷键

cmd + / 快速注释选中行的代码（单行或者多行）
command + Option + /，快速高级的逻辑注释（常用于方法）
option + 单击显示注释指示内容
使用多行注释一段逻辑 /* */，多行注释不可嵌套多行注释

代码片段

Xcode的代码片段(Code Snippets)可以用来自定义代码块，方便快速开发

示例代码：

@property (nonatomic,strong) <#Class#> *<#object#>; ///< <#note#>

关键写法： <#这里是默认提示的文本#>

代码片段-00.png

添加方式步骤1

代码片段-01.png

步骤1图中关键说明

关键字	含义
Title	为你设置的代码短的标题
Summary	方法片段摘要说明
Completion Shortcut	为你设置的快捷代码，当你在Xcode中输入你设置的快捷代码就会出现改代码段
Completion Scopes	为你需要设置的启动作用域，如某些方法内就不能启动快捷代码段

添加方式步骤2

代码片段-02.png

添加方式步骤3(后续修改查看)

代码片段-03.png

生成文档

docxygen http://www.stack.nl/~dimitri/doxygen/index.html
headdoc http://developer.apple.com/opensource/tools/headerdoc.html
appledoc http://gentlebytes.com/appledoc/
docxygen

docxygen 感觉是这 3 个工具中支持语言最多的，可以配置的地方也比较多。我大概看了一下文档，觉得还是比较复杂，而且默认生成的风格与苹果的风格不一致。就去看后面 2 个工具的介绍了。另外，它虽然是开源软件，但是没有将源码放到 github 上让我感觉这个工具的开发活跃度是不是不够。

headerdoc

headerdoc 是 Xcode 自带的文档生成工具。在安装完 Xcode 后，就可以用命令行：headdoc2html + 源文件名来生成对应的文档。我个人试用了一下，还是比较方便的，不过 headerdoc 的注释生成规则比较特别，只生成以 /*! */ 的格式的注释。还有一个缺点是每个类文件对应一个注释文件，没有汇总的文件，这点感觉有点不爽。

appledoc

appledoc 是在 stackoverflow 上被大家推荐的一个注释工具。有几个原因造成我比较喜欢它：
它默认生成的文档风格和苹果的官方文档是一致的，而 doxygen 需要另外配置。
appledoc 就是用 objective-c 生成的，必要的时候调试和改动也比较方便。
可以生成 docset，并且集成到 Xcode 中。这一点是很赞的，相当于在源码中按住 option 再单击就可以调出相应方法的帮助。
appledoc 源码在 github 上，而 doxygen 在 svn 上。我个人比较偏激地认为比较活跃的开源项目都应该在 github 上。
相对于 headerdoc，它没有特殊的注释要求，可以用 /** */ 的格式，也可以兼容 /*! */ 的格式的注释，并且生成的注释有汇总页面。

以下步骤主要参考该篇博客， https://blog.csdn.net/xborong/article/details/85057696 </p>
appledoc-官方博客
 appledoc-ibireme博客
 appledoc-唐巧博客
的博客中的过程都有点问题

appledoc version: 2.2.1 (build 1334)

工具安装

git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh

脚本编写

#!/bin/bash
appledoc \
--output ./Doc \
-i *.m \
--project-name "IGUIKit" \
--project-company "Tencent" \
--no-create-docset \
--keep-undocumented-objects \
--keep-undocumented-members \
--no-warn-undocumented-object \
--no-warn-undocumented-member \
./IGUIKit

appledoc-脚本说明.png

生成的文档截图样式

appledoc-ET-01.png

appledoc-ET-10.png

appledoc-ET-11.png

appledoc-ET-12.png

结语

关于注释，两年前自己就做过一次较为全面的了解，算是形成了自己的一套注释风格与规范，现在进一步再总结，过程中借鉴了Apple本身的注释风格，一些开源框架的注释风格，以及一些网上的博客，算是查缺补漏，也希望能够帮助到各位。

注释的写法那么多，最关键的目的还是要写，为了更好的阅读代码。至于你喜欢什么样的注释风格，自己喜欢的风格或者与团队相近即可。

如果有什么建议或问题，欢迎沟通交流。

最全最详细的注释使用说明

最全最详细的注释使用说明

前言

注释的作用

常用的注释分类

环境介绍

代码注释

单行注释

行尾注释

多行注释

手动写的样式：

Xcode生成的样式：

参数list：

附加：

特殊功能注释

Pragma mark

注释标签

warming

attribute

iOS-Foundation使用

AFNetworking使用

SDWebImage使用

高级应用-生成注解

注释的使用

主要使用快捷键

代码片段

步骤1图中关键说明

生成文档

工具安装

脚本编写

生成的文档截图样式

结语

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读