Xcode中代码注释编写的一些小技巧

目录
  • 前言
  • Objective-C的代码注释
  • Swift的代码注释
  • Objective-C和Swift的注释风格现在已经统一
  • 快速修改注释
  • 参考文档
  • 总结

前言

码农总是在搬砖,日复一日,年复一年,有的时候都会麻木。

代码大家都会写,但是把注释写好却是一个技术活。

下面这段话,很好的说明了写好注释的感觉:

注释代码很像清洁你的厕所——你不想干,但如果你做了,这绝对会给你和你的客人带来更愉悦的体验。—— Ryan Campbell

今天给大家聊的就是在Xcode中,代码注释编写小技巧。

Objective-C的代码注释

很久很久以前,在Xcode还可以安装插件的时代,iOSer都通过VVDocument来编写代码注释的。

代码注释的风格一般都是这样的,代码出自IQKeyboardManager/IQBarButtonItem

#import <UIKit/UIBarButtonItem.h>

@class NSInvocation;

/**
 IQBarButtonItem used for IQToolbar.
 */

@interface IQBarButtonItem : UIBarButtonItem

/**
 Boolean to know if it's a system item or custom item
 */
@property (nonatomic, readonly) BOOL isSystemItem;

/**
 Additional target & action to do get callback action. Note that setting custom target & selector doesn't affect native functionality, this is just an additional target to get a callback.

 @param target Target object.
 @param action Target Selector.
 */
-(void)setTarget:(nullable id)target action:(nullable SEL)action;

/**
 Customized Invocation to be called when button is pressed. invocation is internally created using setTarget:action: method.
 */
@property (nullable, strong, nonatomic) NSInvocation *invocation;

@end

OC的注释是通过/** */这样的形式进行编写的。

分隔符使用的是这种风格:

#pragma mark - 这个是一个分割符

需要注意的是这个-非常的重要,通过这个-,在查看代码的时候,可以生成分隔线,让代码结构看的更为清晰。

Swift的代码注释

随着Swift语言发布,在Swift中编写注释的风格就所有不同了:

extension NSObject {

    /// 对象获取类的字符串名称
    public var className: String {
        return runtimeType.className
    }

    /// 类获取类的字符串名称
    public static var className: String {
        return String(describing: self)
    }

    /// NSObject对象获取类型
    public var runtimeType: NSObject.Type {
        return type(of: self)
    }

    /// 这是一个例子函数
    /// - Parameter arg:
    /// - Parameter argument: 传入Int类型的参数
    /// - Returns: 返回Int类型的参数
    public func afunction(argument: Int) -> Int {
        return argument
    }
}

Swift的注释是通过/// 这样的形式进行编写的。

分隔符使用的是这种风格:

//MARK: - 绑定

Swift中的//MARK:这个-也是起到生成分隔线的作用。

Objective-C和Swift的注释风格现在已经统一

如果你现在通过alt+cmd+/在OC和Swift中编写注释的时候,就会发现现在的注释都变成了Swift的这个中风格了:

我个人建议是:以前代码注释就让它去吧,现在就都是用这个统一风格。

快速修改注释

一个函数写好了,注释也写好,但是有的时候计划没有变化快,函数添加了新的参数,这个注释难道要手动添加?

别急,其实Xcode也为我们提供了快捷方式,我们继续看例子,这个函数我在之前的基础上添加了一个num参数,但是注释还是之前的样子:

cmd+鼠标左键点击,我们可以看到左侧出现了一个菜单,点击Add Documentation

我们需要添加的参数它就来了,这样就可以直接添加注释了。

大家有兴趣可以把菜单的选项都点击试试,也许有意外的惊喜,比如Convert Function to Async,await/async。

参考文档

VVDocumenter

总结

从VVDocument到注释的统一,Xcode一直都在做改进,虽然依旧不尽人意。

但是写好注释,也算是码农的一个基本素养吧,大家加油修炼。

到此这篇关于Xcode中代码注释编写小技巧的文章就介绍到这了,更多相关Xcode代码注释编写内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

时间: 2021-10-26

iOS Xcode创建文件时自动生成的注释方法

之前换了电脑,发现用xcode新建文件生成的注释变成了我不想要的效果(如下图) 一.修改系统默认注释 下面分别描述一下"创建者"."创建时间"."机构名称"以及"类名前缀"如何编辑. 1.编辑创建者: 进入路径:系统偏好设置/用户与群组/右击当前用户进入"高级选项" 编辑"全名"为需要的名称,如图: 2.编辑"创建时间"格式: 进入路径:系统偏好设置/日期与时间/打开

PHP上传文件时自动分配路径的方法

本文实例讲述了PHP上传文件时自动分配路径的方法.分享给大家供大家参考.具体分析如下: 网站上传文件时,如果是小的企业站,放在一个目录还没问题,当网站大了,上传的文件多了,我们就不能放在同一个目录了,这里我们就来讲讲用PHP自动给上传的文件分配路径的方法. PHP分配上传文件的路径实例 主要程序片段如下: 复制代码 代码如下: <?php    /*数字方式分配路径*/    function allotPath($id, $extend='jpg') {       $folders = st

python创建文件时去掉非法字符的方法

windows系统中文件名不能包含 \ / : * ? " < > |想要创建必须过滤掉这些字符 def setFileTitle(self,title): fileName = re.sub('[\/:*?"<>|]','-',title)#去掉非法字符 self.file = open(fileName + ".txt","w+") 利用正则去掉非法的字符. 以上这篇python创建文件时去掉非法字符的方法就是小编分享

Pycharm在创建py文件时,自动添加文件头注释的实例

1.选择File -> Settings 2.选择 File and Code Templates -> Files -> Python Script 编辑代码的样式 #!/usr/bin/env python # encoding: utf-8 ''' @author: caopeng @license: (C) Copyright 2013-2017, Node Supply Chain Manager Corporation Limited. @contact: deamoncao

实现core文件自动生成配置文件的方法

本文讲述了实现core文件自动生成的配置方法,具体执行步骤如下: 1.编辑环境配置文件,让shell启动时自动设置ulimit vi /etc/profile ulimit -c unlimited > /dev/null 2>&1 2.更改core文件生成路径 vi /etc/sysctl.conf kernel.core_uses_pid = 1 kernel.core_pattern=/tmp/core-%e-%p 3.sysctl配置生效 sysctl -p /etc/sysc

对Pycharm创建py文件时自定义头部模板的方法详解

如下所示: # -*- coding: utf-8 -*- """ ------------------------------------------------- File Name: ${NAME} Description : Author : ${USER} date: ${DATE} ------------------------------------------------- Change Activity: ${DATE}: ----------------

php实现根据url自动生成缩略图的方法

本文实例讲述了php实现根据url自动生成缩略图的方法,是非常实用的功能.分享给大家供大家参考.具体方法如下: 原理:设置apache rewrite ,当图片不存在时,调用php创建图片. 例如: 原图路径为:http://localhost/upload/news/2013/07/21/1.jpg 缩略图路径为:http://localhost/supload/news/2013/07/21/1.jpg 当访问 http://localhost/supload/news/2013/07/21

iOS读取txt文件出现中文乱码的解决方法

一.情景描述: 后台给一个txt文件,编码是utf-8,在Mac电脑Xcode开发环境下读取txt文件内容,汉字会出现乱码,英文没有乱码这种情况. 二.尝试解决方法: 修改编码格式,尝试了NSUTF16StringEncoding,NSUTF8StringEncoding,NSASCIIStringEncoding编码等,出现的问题有时是中文乱码,有时是utf-8不能打开文件问题,最终问题都没能解决. 三.猜测原因: txt文件是从window电脑上创建,有可能和环境有关,第二,编码问题. 四.

使用python脚本自动生成K8S-YAML的方法示例

1.生成 servie.yaml 1.1.yaml转json service模板yaml apiVersion: v1 kind: Service metadata: name: ${jarName} labels: name: ${jarName} version: v1 spec: ports: - port: ${port} targetPort: ${port} selector: name: ${jarName} 转成json的结构 { "apiVersion": "

python下载文件时显示下载进度的方法

本文实例讲述了python下载文件时显示下载进度的方法.分享给大家供大家参考.具体分析如下: 将这段代码放入你的脚本中,类似:urllib.urlretrieve(getFile, saveFile, reporthook=report) 第三个参数如下面的函数定义report,urlretrieve下载文件时会实时回调report函数,显示下载进度 def report(count, blockSize, totalSize): percent = int(count*blockSize*10