iOS 规范篇 -《规范注释》

开发过程中,注释重不重要,这个你自己琢磨吧!

规范的注释能让你最快了解到代码的大概功能,重现当初处理代码时的思维逻辑.同时能让新同事最快上手或者了解你的代码.给人的感觉就是专业,靠谱.另外一个很重要的原因就是,规范的代码注释,我们可以通过Appledoc-Objective-C文档生成工具来快速生成非常专业的API技术文档(苹果原生的技术文档相似).因此,我们开发必须要有规范的文档注释.

Appledoc使用传送门

Appledoc-Objective-C文档生成工具
开源框架：Appledoc——Objective-C文档生成工具使用教程

规范注释

强烈推荐 - Objective-C规范注释心得

本人习惯

以前有插件,后来就....
现在我是利用保存的代码块片段来快速注释😓,通过自定义代码块,类似下面截图

• Code@Doc#XXX
  • Code为了便于记忆
  • @Doc是表示一个大分类的代码块片段,比如Doc就是我自定义的规范文档注释.
  • #XXX表示大分类下的某个特定的一项

屏幕快照 2018-06-02 18.51.38.png

下面是具体的规范注释代码片段

假如使用Appledoc,下面的规范注释将会生成非常专业的技术API文档.

//通常用来注释某个属性
/** <#简短注释#> */

//通常用来注释某个属性(多行)
/// <#简短描述,如属性描述#>

//通常用来注释某个类
/**
 --------------------------------------------------------------
 `<#类名#>`<#简介#>
 ## <#子选项#>
 <#子选项描述#>.
 ## warning
 @warning <#警告提醒信息#>.
 --------------------------------------------------------------
 */

//通常用来展示一些示例代码
/**
 --------------------------------------------------------------
 ##示例代码
 <#示例代码(需要按tab缩进)#>
 --------------------------------------------------------------
 */

//注意事项:参数必须是在对应方法中,不然会报警告,
@deprecated  必须使用DEPRECATED_MSG_ATTRIBUTE,不然会报警告
@return 必须有return值,不然会警告

/**
 *  <#详细说明这个方法怎么用#>
 *
 *  @brief <#简要描述#>
 *
 *  @param <#参数#> - <#参数描述#>
 *  @param <#参数#> - <#参数描述#>
 *  @param <#参数#> - <#参数描述#>
 *
 *  @return <#返回结果描述#>
 *  @warning <#警告#>
 *
 *  @since <#哪个版本起效#>
 *  @deprecated <#哪个版本废弃 , 方法后面需要添加DEPRECATED_MSG_ATTRIBUTE("use test: instead")#>
 *  @see <#对应的方法,如-(instancetype)init DEPRECATED_MSG_ATTRIBUTE("use test: instead")#>;
 */

//在文档中,起到大标题分割的作用
///-------------------------------
/// @name <#生成文档中的大标题#>
///-------------------------------

参考:

强烈推荐 - Objective-C规范注释心得
开源框架：Appledoc——Objective-C文档生成工具使用教程