Dart Comments

Dart Comments

Comments are notes written inside Dart source code. The Dart compiler ignores comments when it executes the program, so comments do not affect the program output.

Developers use Dart comments to explain code, record implementation details, document public APIs, and temporarily exclude code while testing. Comments should clarify why the code exists rather than repeat what an obvious statement already does.

Dart supports three main comment styles:

1. Single Line Comments
2. Block (Multi-line) Comments
3. Documentation Comments

Dart Single-Line Comments with //

To write a single-line comment in Dart, use two forward slashes, //. Everything after // on the same line is treated as a comment.

void main(){
	//this is comment
	//this is another comment
}

A single-line comment may appear on its own line or after a Dart statement.

void main() {
  // Store the number of completed lessons.
  int completedLessons = 4;

  int totalLessons = 10; // Total lessons in the course.

  print(completedLessons);
  print(totalLessons);
}

4
10

The comments are visible in the source code but do not appear in the program output.

Dart Block Comments with /* and */

A Dart block comment begins with /* and ends with */. It can span one or more lines.

Dart Program

void main(){
	/*
	This is a block comment.
	It can contain multiple lines as comment.
	Another line in this block comment.
	*/
}

Block comments are useful when an explanation needs several lines or when a section of code must be temporarily excluded during testing.

void main() {
  /* Calculate the final price after applying
     a fixed discount to the original price. */
  double originalPrice = 80.0;
  double discount = 10.0;
  double finalPrice = originalPrice - discount;

  print(finalPrice);
}

70.0

Nested Block Comments in Dart

Dart supports nested block comments. A block comment can contain another complete /* ... */ comment.

void main() {
  /* Outer comment
     /* Nested comment */
     End of outer comment
  */

  print('Dart comments');
}

Dart comments

Nested block comments can be helpful when temporarily commenting out code that already contains block comments. Even so, version control is usually a better place to preserve code that is no longer needed.

Dart Documentation Comments with ///

Dart documentation comments describe libraries, classes, constructors, methods, functions, fields, and other declarations. Write a documentation comment immediately before the declaration it documents.

The usual documentation comment style begins each line with ///. Development tools and dart doc can use these comments to display API documentation.

Dart Program

///Documentation Comments
///Some description about main() method.
void main(){
	
}

The following example documents a function, its parameter, and its return value.

/// Returns the sum of [first] and [second].
int add(int first, int second) {
  return first + second;
}

void main() {
  print(add(4, 6));
}

10

Square brackets such as [first] and [second] create references to identifiers in generated Dart API documentation.

Dart Documentation Comments with /** and */

Dart also recognizes block-style documentation comments that begin with /** and end with */. The /// style is generally easier to read and edit, but both styles can document a declaration.

/**
 * Converts a temperature from Celsius to Fahrenheit.
 */
double toFahrenheit(double celsius) {
  return (celsius * 9 / 5) + 32;
}

Difference Between Dart Regular Comments and Documentation Comments

Dart comment syntax	Primary use	Processed as API documentation
// comment	Short implementation note	No
/* comment */	Multi-line explanation or temporarily excluded code	No
/// comment	Documentation for a declaration	Yes
/** comment */	Block-style documentation for a declaration	Yes

Use regular comments for implementation details that help someone read the source code. Use documentation comments for information that users of a class, function, or library need to understand.

Temporarily Comment Out Dart Code

You can place // before a statement to prevent that line from running while testing a program.

void main() {
  print('Application started');
  // print('Debug information');
  print('Application finished');
}

Application started
Application finished

The commented statement remains in the file but is not executed. This technique is suitable for brief testing. Remove obsolete code instead of leaving large commented-out sections in maintained projects.

Useful Practices for Writing Dart Comments

• Explain why a decision was made when the reason is not obvious from the code.
• Keep comments accurate when the related Dart code changes.
• Do not describe simple statements that are already self-explanatory.
• Place a comment close to the code or declaration it describes.
• Use /// for public APIs that need generated documentation.
• Prefer clear variable and function names over comments that compensate for unclear naming.
• Remove outdated comments and temporary debugging notes before publishing code.

Dart Comments Example Program

The following program uses single-line, block, and documentation comments together.

/// Calculates the area of a rectangle.
double calculateArea(double width, double height) {
  return width * height;
}

void main() {
  // Dimensions are measured in centimeters.
  double width = 8.0;
  double height = 5.0;

  /* Call the documented function and store
     the calculated rectangle area. */
  double area = calculateArea(width, height);

  print('Area: $area square centimeters');
}

Area: 40.0 square centimeters

Dart Comments Frequently Asked Questions

How do you write a comment in Dart?

Use // for a single-line comment, /* ... */ for a block comment, or /// for a documentation comment attached to a Dart declaration.

Do Dart comments affect program execution?

No. Dart comments are ignored during normal program execution. They are included to help developers understand or document the source code.

Can Dart block comments be nested?

Yes. Dart supports correctly paired block comments inside other block comments. This differs from programming languages in which the first closing */ always ends the entire comment.

What is the difference between // and /// in Dart?

// creates a regular source-code comment. /// creates a documentation comment that tools can associate with the following Dart declaration and include in generated API documentation.

Should comments explain what Dart code does?

A useful comment usually explains intent, assumptions, or reasons that are not clear from the code itself. Comments that merely restate obvious code add little value and can become outdated.

Dart Comments Summary

Dart provides // for single-line comments, /* ... */ for block comments, and /// or /** ... */ for documentation comments. Regular comments explain implementation details, while documentation comments describe declarations for developers who use an API.

In this Dart Tutorial, we learned different types of commenting techniques and how to use them.