Comments in Dart

Comments are non-executable lines of text used to explain code. They are ignored by the Dart compiler and exist purely to make code easier to read, understand, and maintain.

In professional Flutter development, good commenting is a sign of clear thinking and clean code.

---

Why Comments Are Important

Comments help:

• Explain why code exists, not just what it does

• Make code easier for others (and your future self) to understand

• Document logic, assumptions, and edge cases

• Improve collaboration in team projects

In Flutter projects, comments are especially useful when dealing with:

• Complex UI logic

• State management

• API integration

• Business rules

---

Types of Comments in Dart

Dart supports three main types of comments:

1. Single-line comments

2. Multi-line comments

3. Documentation comments

---

1. Single-Line Comments (//)

Single-line comments start with // and continue until the end of the line.

Copyvoid main() {
  // This is a single-line comment
  print('Hello Dart'); // Inline comment
}

When to Use

• Short explanations

• Clarifying logic

• Temporarily disabling a line of code

---

2. Multi-Line Comments (/* */)

Multi-line comments are written between /* and */ and can span multiple lines.

Copyvoid main() {
  /*
    This is a multi-line comment.
    It can explain complex logic
    or provide additional context.
  */
  print('Flutter Development');
}

When to Use

• Explaining complex blocks of logic

• Writing notes or warnings

• Commenting out large code sections temporarily

---

3. Documentation Comments (/// and /** */)

Documentation comments are special comments used to generate API documentation. They are written using /// or /** */.

Single-Line Documentation Comment

Copy/// Calculates the sum of two numbers
int add(int a, int b) {
  return a + b;
}

Multi-Line Documentation Comment

Copy/**
 * This function greets the user.
 *
 * [name] is the name of the user.
 */
void greet(String name) {
  print('Hello, $name');
}

Documentation comments are commonly used in:

• Packages

• Libraries

• Public APIs

---

Documentation Comments in Flutter

In Flutter, documentation comments are often used for:

• Custom widgets

• Reusable components

• Public methods

Copy/// A custom button widget used across the app
class CustomButton {
  // Widget implementation
}

Good documentation comments make your code self-explanatory and professional.

---

Commenting Best Practices

Follow these rules for clean code:

1. Do not explain obvious code

2. Explain why, not what

3. Keep comments up to date

4. Avoid excessive commenting

5. Use documentation comments for reusable code

Bad example:

Copyint age = 22; // storing age

Good example:

Copy// Age is used to calculate user eligibility
int age = 22;

---

Common Beginner Mistakes

• Over-commenting simple code

• Leaving outdated comments

• Commenting instead of refactoring

• Using comments to hide bad code

---

Summary

In this lesson, you learned:

• What comments are

• Types of comments in Dart

• How documentation comments work

• Best practices for professional code

Writing good comments improves code quality, teamwork, and long-term maintainability.