Small knowledge, big challenge! This paper is participating in theEssentials for programmers”Creative activities.

This paper also participates inProject DigginTo win the creative gift package and challenge the creative incentive money.

preface

The coder is always moving bricks, day after day, year after year, sometimes numb.

Everyone can write code, but getting comments right is a skill.

Here’s a good example of what it feels like to write a good comment:

Commenting code is a lot like cleaning your toilet — you don’t want to do it, but if you do, it will definitely make the experience more enjoyable for you and your guests. – Ryan Campbell

Today, I’m going to talk about some tips for writing code comments in Xcode.

Code comments in Objective-C

A long, long time ago, when Xcode could install plug-ins, iOSer wrote code comments via VVDocument.

Code comments of style is so commonly, code from 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
Copy the code

OC comments are written in the form /** */.

The delimiter uses this style:

#pragma mark - This is a separatorCopy the code

The thing to notice about this — and this is very important — is that when you look at your code, you can generate dividers to make the structure of your code a little bit clearer.

Swift code comments

With the release of Swift, the style of writing comments in Swift has changed completely:

Extension NSObject {/// public var className: Public static var className: String {return runtimeType.className} public static var className: String {return String(describing: Public var runtimeType: nsobject. Type {return Type (of: // -parameter argument: // -parameter argument: // -parameter argument: // -parameter argument: // -parameter argument: // -parameter argument: Public func afunction(argument: Int) -> Int {return argument}}Copy the code

Swift comments are written in the form ///.

The delimiter uses this style:

/ / MARK: - bindingCopy the code

//MARK in Swift: This – also acts as a separator line.

The annotation styles of Objective-C and Swift are now unified

If you now use Alt + CMD +/ to write comments in OC and Swift, you will see that the comments are now in the Swift style:

My personal advice is: leave the code comments alone, and use the same style now.

Quick modification comments

A function is written and comments are written, but sometimes the plan does not change quickly and new parameters are added to the function. Should the comments be added manually?

Don’t worry, Xcode also provides shortcuts. Let’s continue with the example. I added a num argument to this function, but the comment remains the same as before:

CMD + left mouse click and a menu appears on the left. Click Add Documentation

It comes with the parameters we need to add, so we can add comments directly.

If you are interested, you can click all the menu options and try them out. You may get unexpected surprises, such as Convert Function to Async, await/ Async.

Reference documentation

VVDocumenter

conclusion

From VVDocument to uniform comments, Xcode is making improvements all the time, though it’s still not great.

But write a good note, it is also a basic quality of code farmers, we refuel cultivation.

We’ll see you next time.