Comments and documentation markup in Swift - Deep Dive

Overview - Comments and documentation markup

What is it?

Comments are notes in code that explain what the code does, but they do not run when the program runs. Documentation markup is a special way to write comments so tools can create helpful guides automatically. In Swift, comments help programmers understand code better and keep it organized. They can be simple notes or detailed explanations that describe how parts of the code work.

Why it matters

Without comments and documentation, code can be confusing and hard to fix or improve, especially when many people work on it or when you return to it after a long time. Good comments save time and prevent mistakes by making the code's purpose clear. Documentation markup helps create easy-to-read manuals that explain how to use code parts, making teamwork and learning faster and smoother.

Where it fits

Before learning comments, you should know basic Swift syntax and how to write simple programs. After mastering comments and documentation markup, you can learn about code organization, testing, and creating libraries or frameworks that others can use.

Mental Model

Core Idea

Comments and documentation markup are like labels and instruction manuals inside your code that explain what it does without changing how it works.

Think of it like...

Imagine building a LEGO set: comments are the sticky notes you put on pieces to remind yourself what they do, and documentation markup is the instruction booklet that helps others build the same set correctly.

Code with comments and documentation markup:

┌─────────────────────────────┐
│ // This function adds two numbers  │  ← Simple comment
│ func add(a: Int, b: Int) -> Int { │
│     return a + b                  │
│ }                              │
│ /**                           │
│  Adds two integers and returns │
│  the result.                  │
│  - Parameters:                │
│    - a: First number          │
│    - b: Second number         │
│  - Returns: Sum of a and b    │
│ */                            │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Basic single-line comments

Concept: Learn how to write simple notes in code using single-line comments.

In Swift, you can write a single-line comment by starting the line with two slashes `//`. Everything after `//` on that line is ignored by the computer and is only for humans reading the code. Example: // This is a comment explaining the next line let number = 5 The computer runs `let number = 5` but ignores the comment.

Result

The program runs normally, but the comment helps anyone reading the code understand what `number` means.

Understanding single-line comments is the first step to making your code clearer and easier to follow.

2

Foundation

Multi-line comments for longer notes

Concept: Use multi-line comments to write explanations that span several lines.

Sometimes you need more space to explain something. Swift lets you write multi-line comments by starting with `/*` and ending with `*/`. Everything between these marks is ignored by the computer. Example: /* This is a multi-line comment. It can explain complex ideas or temporarily disable code. */ let x = 10 You can also nest multi-line comments inside each other.

Result

You can write detailed notes or disable blocks of code without deleting them.

Knowing multi-line comments helps you document complex parts or test code safely by hiding it temporarily.

3

Intermediate

Documentation comments with markup

🤔Before reading on: do you think documentation comments are just longer comments or do they have a special format? Commit to your answer.

Concept: Swift uses special comment styles to create documentation that tools can read and turn into guides.

Documentation comments start with `///` for single lines or `/** ... */` for blocks. They support special markup tags like `- Parameters:` and `- Returns:` to describe functions clearly. Example: /// Adds two numbers and returns the result. /// - Parameters: /// - a: First number /// - b: Second number /// - Returns: The sum of a and b func add(a: Int, b: Int) -> Int { return a + b } Tools like Xcode use these comments to show helpful hints and generate documentation pages.

Result

Your code becomes self-explanatory and tools can create user-friendly manuals automatically.

Understanding documentation markup unlocks powerful ways to communicate your code's purpose to others and to yourself.

4

Intermediate

Using comments to explain intent, not code

🤔Before reading on: do you think comments should explain what the code does line-by-line or why it does it? Commit to your answer.

Concept: Good comments focus on why the code exists or what problem it solves, not just what each line does.

Instead of repeating the code, comments should explain the reason behind it. Example: // Calculate the total price including tax let totalPrice = price * 1.08 This comment tells why we multiply by 1.08, which is more helpful than just saying 'multiply price'. Avoid comments like: // Add 1 to x x = x + 1 because the code already says that clearly.

Result

Comments become meaningful guides that help others understand your thinking and decisions.

Knowing what to comment prevents clutter and makes your notes truly valuable.

5

Intermediate

Commenting out code safely

🤔Before reading on: do you think commenting out code is a good way to delete it permanently? Commit to your answer.

Concept: Comments can temporarily disable code without deleting it, useful for testing or debugging.

If you want to stop a piece of code from running but keep it for later, you can comment it out. Example: // let oldValue = calculateOldValue() This line won't run but stays in the file. Use multi-line comments to disable bigger blocks: /* func oldFunction() { // old code } */ Remember to remove unused code eventually to keep your project clean.

Result

You can test changes safely without losing previous code.

Understanding this helps avoid accidental permanent deletions and supports safer experimentation.

6

Advanced

Generating documentation with Swift tools

🤔Before reading on: do you think documentation comments automatically create manuals or do you need extra steps? Commit to your answer.

Concept: Swift tools can read documentation markup and generate formatted documents or show inline help in editors.

Xcode and other tools parse documentation comments to provide quick help when you use functions or classes. You can also generate full HTML or other formats using tools like Jazzy. Example: /// Adds two numbers. /// - Parameters: /// - a: First number /// - b: Second number /// - Returns: Sum of a and b func add(a: Int, b: Int) -> Int { return a + b } Running documentation tools creates user-friendly guides from these comments.

Result

Your codebase gains professional-quality documentation that helps users and developers.

Knowing how to generate docs turns comments from simple notes into powerful communication tools.

7

Expert

Advanced markup and customization tricks

🤔Before reading on: do you think documentation markup supports custom tags or rich formatting? Commit to your answer.

Concept: Swift documentation markup supports advanced features like code blocks, lists, and custom tags to create rich, readable docs.

You can add code examples inside comments using triple backticks: /// Example usage: /// ```swift /// let result = add(a: 2, b: 3) /// print(result) // 5 /// ``` You can also use lists and emphasize text: /// - Important: /// Use this function only with positive numbers. Custom tags and formatting help create clear, professional documentation. Some tools allow you to extend markup with your own tags for special needs.

Result

Your documentation looks polished and can teach users effectively with examples and warnings.

Mastering advanced markup elevates your documentation from basic notes to comprehensive guides that reduce support and errors.

Under the Hood

When Swift code runs, the compiler ignores comments completely—they do not affect the program's behavior or performance. Documentation comments are specially recognized by tools like Xcode's source editor and external documentation generators. These tools parse the markup syntax inside comments to create structured help content, tooltips, and formatted manuals. This separation keeps code clean and fast while enabling rich explanations outside the executable code.

Why designed this way?

Comments were designed to be ignored by the compiler to avoid slowing down programs or causing errors. Documentation markup evolved to standardize how explanations are written so tools can automate help generation, improving developer productivity. This design balances code clarity, performance, and maintainability. Alternatives like embedding documentation in separate files were less convenient and prone to getting out of sync with code.

┌───────────────┐
│ Swift Source  │
│ Code + Comments│
└──────┬────────┘
       │ Compiler ignores comments
       ▼
┌───────────────┐
│ Executable    │
│ Code Only     │
└───────────────┘

Documentation Tools
┌───────────────┐
│ Parse comments│
│ with markup   │
└──────┬────────┘
       ▼
┌───────────────┐
│ Generate docs │
│ (HTML, tooltips)│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do comments slow down your Swift program when it runs? Commit to yes or no.

Common Belief: Comments make the program slower because they add extra text.

Reality: Comments are completely ignored by the Swift compiler and do not affect the program's speed or size.

Why it matters: Believing this might make learners avoid writing helpful comments, making code harder to understand and maintain.

Quick: Should you write comments that just repeat what the code says? Commit to yes or no.

Common Belief: Good comments explain exactly what each line of code does, even if obvious.

Reality: Effective comments explain why the code exists or what it intends, not just what it does line-by-line.

Why it matters: Repeating code wastes time and clutters files, making it harder to find useful explanations.

Quick: Do documentation comments automatically create manuals without extra tools? Commit to yes or no.

Common Belief: Writing documentation comments alone is enough to produce user manuals.

Reality: Documentation comments need tools like Xcode or Jazzy to generate readable manuals or help pop-ups.

Why it matters: Expecting automatic manuals without tools can lead to confusion and missed opportunities to create helpful docs.

Quick: Can you nest multi-line comments inside each other in Swift? Commit to yes or no.

Common Belief: Multi-line comments cannot be nested; doing so causes errors.

Reality: Swift supports nesting multi-line comments, allowing you to comment out blocks that already contain comments.

Why it matters: Knowing this prevents frustration when trying to disable code blocks that include comments.

Expert Zone

1

Documentation comments can include rich formatting like code blocks and lists, which many developers overlook, missing chances to create clearer docs.

2

Nested multi-line comments allow safe temporary disabling of complex code sections, a feature not common in all languages.

3

Xcode's quick help feature uses documentation markup to show inline hints, but the quality depends on how well you write your comments.

When NOT to use

Avoid over-commenting trivial code or writing comments that duplicate code logic. Instead, refactor code to be self-explanatory. For large projects, use external documentation tools and keep comments focused on intent and usage rather than implementation details.

Production Patterns

In professional Swift projects, developers use documentation markup extensively to generate API references and quick help. Comments are used to explain complex algorithms, assumptions, and usage constraints. Teams often enforce comment quality through code reviews and automated tools that check for missing documentation.

Connections

Code readability

Comments and documentation markup directly improve code readability.

Understanding how to write effective comments helps make code easier to read and maintain, which is the core goal of readable code.

Technical writing

Documentation markup is a form of technical writing embedded in code.

Learning documentation markup improves your technical writing skills, enabling you to communicate complex ideas clearly and precisely.

User manuals in product design

Documentation markup creates manuals similar to user guides in product design.

Knowing how to write clear documentation in code parallels creating helpful user manuals, emphasizing clarity and user understanding across fields.

Common Pitfalls

#1 Writing comments that just repeat the code.

Wrong approach:

// Increment x by 1
x = x + 1

Correct approach:

// Increase x to track the number of attempts
x = x + 1

Root cause:

Misunderstanding that comments should explain why, not what, leads to redundant and unhelpful notes.

#2 Leaving outdated comments after code changes.

Wrong approach:

// This function multiplies by 2
func double(x: Int) -> Int {
return x * 3
}

Correct approach:

// This function multiplies by 3
func double(x: Int) -> Int {
return x * 3
}

Root cause:

Failing to update comments when code changes causes confusion and mistrust in documentation.

#3 Using comments to disable large code blocks without nesting support.

Wrong approach:

/*
func test() {
/* inner comment */
}
*/

Correct approach:

/*
func test() {
/* inner comment */
}
*/ // Swift supports nested comments, so this works correctly

Root cause:

Not knowing Swift supports nested comments leads to errors or frustration when commenting out code.

Key Takeaways

Comments are notes in code that help humans understand what the code does without affecting how it runs.

Documentation markup uses special comment styles to create structured explanations that tools can turn into manuals and inline help.

Good comments explain why code exists or what it intends, not just what each line does.

Swift supports both single-line and nested multi-line comments, giving flexibility in writing notes or disabling code.

Using documentation comments well improves teamwork, learning, and maintenance by making code self-explanatory and professionally documented.

Practice

1. What is the main purpose of comments in Swift code?

easy

A. To create new variables

B. To make the code run faster

C. To explain the code for better understanding

D. To store user data

Solution

1. Step 1: Understand what comments do

   Comments are notes in the code that do not affect how the program runs but help explain what the code does.

2. Step 2: Identify the purpose of comments

   Comments make the code easier to read and understand for yourself and others who read the code later.

3. Final Answer:

   To explain the code for better understanding -> Option C

4. Quick Check:

   Comments explain code [OK]

Hint: Comments explain code, not run it or store data [OK]

Common Mistakes:

• Thinking comments speed up code
• Confusing comments with variables
• Using comments to store data

2. Which of the following is the correct syntax for a single-line comment in Swift?

easy

A. # This is a comment

B. /* This is a comment */

C.

D. // This is a comment

Solution

1. Step 1: Recall Swift comment syntax

   Swift uses // for single-line comments and /* */ for multi-line comments.

2. Step 2: Match the correct syntax

   // This is a comment uses // which is the correct single-line comment syntax in Swift.

3. Final Answer:

   // This is a comment -> Option D

4. Quick Check:

   Single-line comment = // [OK]

Hint: Single-line comments start with // in Swift [OK]

Common Mistakes:

• Using /* */ for single-line comments
• Using HTML style comments
• Using # which is not a comment in Swift

3. What will the following Swift code output?

/// Adds two numbers
func add(_ a: Int, _ b: Int) -> Int {
    return a + b
}
print(add(3, 4))

medium

A. 7

B. add(3, 4)

C. /// Adds two numbers

D. Error: Unexpected documentation comment

Solution

1. Step 1: Understand documentation comments effect

   The line starting with /// is a documentation comment and does not affect the code execution.

2. Step 2: Execute the function call

   The function add returns the sum of 3 and 4, which is 7, and print outputs it.

3. Final Answer:

   7 -> Option A

4. Quick Check:

   Documentation comment ignored, output = 7 [OK]

Hint: Documentation comments don't change output, only explain [OK]

Common Mistakes:

• Thinking documentation comments print text
• Expecting error from documentation comments
• Confusing comments with code

4. Identify the error in this Swift code snippet:

/* This is a multi-line comment
func greet() {
    print("Hello")
}
// Missing closing comment delimiter

medium

A. Using // inside multi-line comment is invalid

B. Missing closing */ for multi-line comment

C. Function greet() is not declared properly

D. print statement syntax error

Solution

1. Step 1: Check multi-line comment syntax

   Multi-line comments start with /* and must end with */ to close properly.

2. Step 2: Identify missing closing delimiter

   The code has /* but no closing */, so the comment never ends, causing a syntax error.

3. Final Answer:

   Missing closing */ for multi-line comment -> Option B

4. Quick Check:

   Multi-line comment must close with */ [OK]

Hint: Multi-line comments need /* and */ to open and close [OK]

Common Mistakes:

• Ignoring missing closing comment delimiter
• Thinking // can't be inside multi-line comments
• Assuming function syntax is wrong

5. You want to document a Swift function so that Xcode shows its description and parameters clearly. Which comment style should you use?

func multiply(_ x: Int, _ y: Int) -> Int {
    return x * y
}

hard

A. /// Multiplies two numbers
/// - Parameters:
/// - x: The first number
/// - y: The second number
/// - Returns: The product of x and y

B. /* Multiplies two numbers */

C. // This function multiplies two numbers

D.

Solution

1. Step 1: Understand documentation comment usage

   Documentation comments in Swift use /// and special markup to describe functions and parameters for tools like Xcode.

2. Step 2: Identify the detailed documentation style

   /// Multiplies two numbers /// - Parameters: /// - x: The first number /// - y: The second number /// - Returns: The product of x and y uses /// with - Parameters and - Returns tags, which is the correct way to document for Xcode's quick help.

3. Final Answer:

   /// Multiplies two numbers /// - Parameters: /// - x: The first number /// - y: The second number /// - Returns: The product of x and y -> Option A

4. Quick Check:

   Use /// with parameter tags for documentation [OK]

Hint: Use /// with - Parameters and - Returns for Xcode docs [OK]

Common Mistakes:

• Using single-line or multi-line comments without markup
• Using HTML style comments
• Not including parameter descriptions