In general, follow the comments section in the official guidelines.
Comments should be written in full US English prose, with correct grammar and punctuation.
Correct grammar and punctuation helps the documentation maintain clarity.
All public declarations in your code base, such as classes, enums, functions, properties should have documentation. The outline of the documentation can be inserted in Xcode by pressing CMD
+ Option
+ /
when the cursor is immediately above a method, class, etc or by selecting Xcode menu bar -> Editor -> Structure -> Add Documentation.
Clear documentation promotes others’ better understanding of the source code and facilitates reviews and usages. In addition, Documentation automatically shows up in Xcode code completion and Quick Help to help with precise usage.
public enum ShimmerStyle {
case concealing
case revealing
}
/// The style affects how shimmer is animated
public enum ShimmerStyle {
/// The gradient conceals parts of the subviews as it moves leaving most parts of the subviews unblocked.
case concealing
/// The gradient reveals parts of the subviews as it moves leaving most parts of the subview blocked.
case revealing
}
There are three main purposes of inline comments:
Adding inline comments brings clarity and readability to complex code and logic.
class SomeView: NSView {
private weak var someEventBridge: EventBridge?
}
class SomeView: NSView {
// Using weak here because lifetimes of SomeView and someEventBridge
// are not related. It is possible that someEventBridge outlives SomeView.
private weak var someEventBridge: EventBridge?
}
let finalScore = scores.reduce(0, combine: +) / Double(scores.count)
// Compute the final score as the arithmetic mean of the previous scores
let finalScore = scores.reduce(0, combine: +) / Double(scores.count)
func loadLastCheckpoint() -> GameState? {
let defaultDataPath = getDefaultDataPath()
guard let saveFilePath = defaultDataPath.appendingPathComponent("SaveFile.dat") else {
return nil
}
guard let dataContents = try? NSData(contentsOfFile: saveFilePath) else {
return nil
}
guard let loadedState = GameState.deserialize(dataContents) else {
return nil
}
loadedState.resetToLastCheckpoint()
return loadedState
}
func loadLastCheckpoint() -> GameState? {
// Determine the path to the file on disk
guard let saveFilePath = defaultDataPath.appendingPathComponent("SaveFile.dat") else {
return nil
}
// Load in the serialized state
guard let dataContents = try? NSData(contentsOfFile: saveFilePath) else {
return nil
}
// Deserialize
guard let loadedState = GameState.deserialize(dataContents) else {
return nil
}
// Reset to checkpoint and return
loadedState.resetToLastCheckpoint()
return loadedState
}
Single line and multi line comments in Swift can be written in a few different forms, some of which enable additional features such as markdown to provide richer documentation.
The triple slash style comment, ///
, is preferred for both single line and multi line comments as it allows for the use of markdown inside comments, provides automcomplete and quick help documentation, and is the default for Xcode’s docmentation generation. Additional details about the different comment styles can be found in the official documentation.
class SomeToolbar: UIView {
// Array holding UIViews shown inside toolbar
public var toolbarItems: [UIView]?
}
class SomeToolbar: UIView {
/// Array holding `UIView`s shown inside toolbar
public var toolbarItems: [UIView]?
}
class SomeToolbar: UIView {
/*
Hides the toolbar view.
@param animated: When true, the view will hide with animation
@param completion: Block called after the view is finished hiding
*/
public func hideToolbar(_ animated: Bool, completion: ((Bool) -> Void)?) {
setHidden(true, animated: animated, completion: completion)
}
}
///
style comment used for public method descriptionclass SomeToolbar: UIView {
/// Hides the toolbar view.
///
/// Parameter animated: When true, the view will hide with animation
/// Parameter completion: Block called after the view is finished hiding
public func hideToolbar(_ animated: Bool, completion: ((Bool) -> Void)?) {
setHidden(true, animated: animated, completion: completion)
}
}