Swift Comments

Comments are an essential part of writing clean, maintainable code. In Swift, comments allow you to include non-executable text in your code to explain what your code does, why certain decisions were made, or to provide additional context for other developers (or your future self).

Introduction to Comments

Comments serve several important purposes in programming:

• Explaining complex sections of code
• Documenting function parameters and return values
• Providing context for your implementation choices
• Temporarily disabling code during development
• Creating documentation that can be automatically extracted

Swift offers several ways to write comments, from simple single-line comments to more structured documentation comments.

Types of Comments in Swift

Single-Line Comments

Single-line comments start with two forward slashes (//). Everything after the slashes on that line is considered a comment and is ignored by the Swift compiler.

swift

// This is a single-line comment
let name = "Swift" // This is also a comment, on the same line as code

Multi-Line Comments

Multi-line comments start with a forward slash followed by an asterisk (/*) and end with an asterisk followed by a forward slash (*/). Everything between these delimiters is considered a comment, even if it spans multiple lines.

swift

/* This is a multi-line comment.
   It can span across several lines.
   The Swift compiler will ignore everything
   until it sees the closing delimiter. */

let language = "Swift" /* You can also use
multi-line comments in the middle of a line,
although this is less common */

Nested Comments

Unlike many other programming languages, Swift allows you to nest multi-line comments within other multi-line comments. This can be helpful when commenting out blocks of code that already contain comments.

swift

/* This is the outer comment.
   /* This is a nested comment. */
   Still in the outer comment. */

Documentation Comments

Swift has a special syntax for documentation comments that can be processed by tools like Xcode to generate documentation. These comments use three forward slashes (///) or a multi-line comment with an additional asterisk (/**).

Single-Line Documentation Comments

swift

/// This is a documentation comment for the following function
func greet(person: String) -> String {
    return "Hello, \(person)!"
}

Multi-Line Documentation Comments

swift

/**
 A function that returns a greeting message for a person.
 
 - Parameter person: The name of the person to greet
 - Returns: A greeting message
 */
func greet(person: String) -> String {
    return "Hello, \(person)!"
}

When you use documentation comments, Xcode will display this information in the Quick Help panel:

Markdown in Documentation Comments

Swift documentation comments support Markdown formatting, which allows you to create more structured and readable documentation:

swift

/**
 # Greeting Generator
 
 This function creates a personalized greeting.
 
 ## Usage Example

let message = greet(person: "John") print(message) // Prints "Hello, John!"

- Parameter person: The person's name
- Returns: A formatted greeting string
- Throws: `GreetingError.invalidName` if the name is empty

> Note: This function validates the input name.
*/
func greet(person: String) throws -> String {
   guard !person.isEmpty else {
       throw GreetingError.invalidName
   }
   return "Hello, \(person)!"
}

MARK, TODO, and FIXME Comments

Swift developers commonly use special comment prefixes to organize code:

swift

// MARK: - Public Methods
// These comments help organize your code in Xcode's jump bar

// TODO: Implement user authentication
// Indicates work that needs to be done

// FIXME: This calculation is incorrect when value is negative
// Highlights issues that need to be fixed

In Xcode, MARK comments create visible separations in the jump bar:

swift

// MARK: - Properties

private var name: String = ""
private var age: Int = 0

// MARK: - Initialization

init(name: String) {
    self.name = name
}

// MARK: - Public Methods

func sayHello() {
    print("Hello, \(name)!")
}

Commenting Out Code

During development, you may want to temporarily disable some code without deleting it. Comments are perfect for this purpose:

swift

func processData() {
    // Original implementation
    // let result = slowAlgorithm()
    
    // New faster implementation
    let result = fastAlgorithm()
    
    /* 
    This debug code is commented out in production:
    if debugMode {
        print("Debug info: \(result)")
    }
    */
}

Best Practices for Comments

1. Write clear, concise comments: Focus on why, not what.

swift

// Bad: This increments the counter
counter += 1

// Good: Increment the counter to keep track of failed login attempts
counter += 1

2. Keep comments up to date: Outdated comments are worse than no comments.

3. Use documentation comments for public APIs: This helps other developers understand how to use your code.

4. Comment complex algorithms: Explain the reasoning and approach for complex code.

swift

// Using binary search for performance optimization since the array is sorted
// This reduces search complexity from O(n) to O(log n)
func findElement(_ array: [Int], target: Int) -> Int? {
    // Binary search implementation...
}

5. Avoid obvious comments: Don't add comments for self-explanatory code.

swift

// Bad:
// Set the user's name
user.name = "John"

// Good: (no comment needed for simple operations)
user.name = "John"

Real-World Example: Documenting a Weather App API Client

Here's how you might use comments effectively in a real application:

swift

/**
 # WeatherService
 
 A service that fetches weather data from the WeatherAPI.
 
 ## Usage Example

 let service = WeatherService(apiKey: "your-api-key")
 service.getCurrentWeather(for: "London") { result in
     switch result {
     case .success(let weather):
         print("Temperature: \(weather.temperature)°C")
     case .failure(let error):
         print("Error: \(error)")
     }
 }

 */
class WeatherService {
    // MARK: - Properties
    
    /// The API key used for authentication with the weather service
    private let apiKey: String
    
    /// The base URL for the weather API
    private let baseURL = URL(string: "https://api.weatherservice.com")!
    
    // MARK: - Initialization
    
    /// Creates a new weather service instance
    /// - Parameter apiKey: Your WeatherAPI key
    init(apiKey: String) {
        self.apiKey = apiKey
    }
    
    // MARK: - Public Methods
    
    /// Fetches the current weather for a specific location
    /// - Parameters:
    ///   - location: The city name or location identifier
    ///   - completion: A closure that will be called with the result
    /// - Note: This method requires a valid API key to be configured
    func getCurrentWeather(for location: String, completion: @escaping (Result<WeatherData, WeatherError>) -> Void) {
        // TODO: Implement caching to reduce API calls
        
        guard let url = URL(string: "/current?location=\(location)", relativeTo: baseURL) else {
            completion(.failure(.invalidURL))
            return
        }
        
        /* Temporarily disabled for testing
        if apiKey.isEmpty {
            completion(.failure(.missingAPIKey))
            return
        }
        */
        
        // FIXME: Handle spaces in location names
        let request = URLRequest(url: url)
        
        // Perform network request and process the response...
    }
}

Summary

Comments are a powerful tool for making your Swift code more readable, maintainable, and accessible. By using the appropriate comment style for each situation and following best practices, you can effectively document your code for yourself and other developers.

Key points to remember:

• Use // for single-line comments
• Use /* */ for multi-line comments
• Use /// or /** for documentation comments
• Add MARK:, TODO:, and FIXME: for better code organization
• Write comments that explain why, not what
• Keep comments up to date with code changes

Exercises

1. Take a simple Swift function you've written and add proper documentation comments.
2. Practice using MARK: comments to organize a class into logical sections.
3. Find a complex piece of code and add explanatory comments that would help a beginner understand it.
4. Convert some regular comments in your code to documentation comments and see how they appear in Xcode's Quick Help.

Additional Resources

• Swift Documentation
• Swift Markup Formatting Reference
• Swift Style Guide