It's essential to use comments in code to document our thought process and make it easier for others to understand our code. But comments will be more impactful when we maintain best practices (including when and what to write comments). This blog will discuss best comment practices when working with SwiftUI on iOS application development.
If you are having difficulty understanding the comment examples in this blog post, don't worry. The primary focus of this blog is to understand the purpose of commenting. It is important for every good programmer to have a strong sense of when and how to comment on their code, and this blog aims to help you build that skill.
Jokes apart, let's discuss the Five Effective "when and how":
1. Explain the purpose of a function or method
When writing a function or method, it's important to explain its purpose in a comment clearly. This will help other developers understand the purpose of the function and how it fits into the overall application.
For example:
func getCurrentDate() -> String {
}
2. Explain complex code
If we have written a complex piece of code that may be difficult for others to understand, it's helpful to include comments explaining the logic behind it. This will make it easier for others to follow our thought process and understand how the code functions.
Here is an example of a complex piece of code in Swift with comments explaining the logic behind it:
func findLargestNumber(in array: [Int]) -> Int {
var largest = array[0]
var largestIndex = 0
for (index, element) in array.enumerated() {
if element > largest {
largest = element
largestIndex = index
}
}
return largest
}
In this example, the findLargestNumber(in:) function takes an array of integers as input and returns the largest number in the array. The comments above each block of code explain the purpose of the variables and the logic behind the for loop that iterates through the array and updates the largest number and its index. This will help other developers understand the code and follow the thought process behind it.
If we make changes to our code, it's essential to document those changes in comments. This will help other developers understand the reasoning behind the changes and how they may impact the overall application.
Here is an example of using comments to document changes in Swift code:
override func viewDidLoad() {
super.viewDidLoad()
setUpNewFeature()
}
func setUpNewFeature() {
let newFeature = NewFeature()
newFeature.configure()
}
In this example, we have added a new feature to our view controller and made some changes to the viewDidLoad() method to initialize and configure the new feature. We have also added a property to store the instance of the new feature. To document these changes, we have added a comment at the top of the block of code outlining the changes that were made, including the addition of the new function and the modifications to viewDidLoad().
While it's important to include comments in our code, it's also important to keep them concise and relevant. Avoid writing long, unnecessary comments, as they can clutter our code and make it harder to read.
Here is an example of concise and relevant comments in Swift code:
func distance(x1: Double, y1: Double, x2: Double, y2: Double) -> Double {
let dx = x2 - x1
let dy = y2 - y1
return sqrt(dx*dx + dy*dy)
}
func isInsideCircle(x: Double, y: Double, centerX: Double, centerY: Double, radius: Double) -> Bool {
let distance = self.distance(x1: x, y1: y, x2: centerX, y2: centerY)
return distance < radius
}
In this example, we have defined two functions: distance() and isInsideCircle(). Both functions have concise and relevant comments that explain their purpose and how they work. The comment for distance() explains that it calculates the distance between two points, while the comment for isInsideCircle() explains that it checks if a point is within a circle by calculating the distance between the point and the center of the circle and comparing it to the radius of the circle. These comments help clarify the code's purpose and function, making it easier for other developers to understand and maintain.
In addition to explaining the purpose of our code, comments can also be used to enhance the readability of our code. For example, we can use comments to separate code sections or highlight important points.
Here is an example of using comments to improve readability in Swift code:
func loadData() {
API.loadData { [weak self] result in
guard let self = self else { return }
switch result {
case .success(let data):
self.processAndSaveData(data)
case .failure(let error):
self.handleError(error)
}
}
}
func processAndSaveData(_ data: Data) {
let model = try? JSONDecoder().decode(Model.self, from: data)
try? CoreDataManager.shared.save(model)
}
func handleError(_ error: Error) {
print("Error: \(error)")
}
In this example, we have a class with three functions: loadData(), processAndSaveData(), and handleError(). To improve the readability of the code, we have added comments to separate the different sections and to explain the purpose of each function. The MARK comment at the top of the block of code separates the Data Loading section from the rest of the code, while the comments above each function explain what the function does. These comments help to break up the code and make it easier to understand and follow.
Last Words
In conclusion, following best comment practices when working with Swift on iOS application development is crucial for maintaining clean, well-documented code. By explaining the purpose of our code, documenting changes, and keeping comments concise and relevant, we can make it easier for us and others to understand and work with our code.
For any queries or suggestions, connect with me here.
