The Menace of Dangling Comments in Flutter and Dart

When developing Flutter applications and Dart packages, encountering the dangling comments lint error is a common frustration. This error often arises when documenting libraries and classes, and it signals a problem with how comments are structured within your code.

What are Dangling Comments?

Dangling comments are comments that appear at the beginning of a file or within a class or function, but are not clearly and directly associated with a specific piece of code. They lack a distinct connection to the code they intend to document. Essentially, they "dangle" without a clear purpose, making it difficult to understand what they are supposed to explain. This often happens when comments are placed at the very top of a file without a corresponding declaration immediately following, or when comments are present but the code they were meant to describe has been removed or significantly altered.

How to Resolve Dangling Comment Errors:

The solution to this lint error is straightforward: Ensure that every comment is directly related to a specific element of your code. This means avoiding placing comments at the top of a file without an immediate association with a library, class, or other declaration. Comments must clearly describe the code that immediately follows them.

Here's a breakdown of the resolution:

1. Avoid Top-of-File Isolation: Do not place comments at the very beginning of a file unless they are directly followed by the corresponding library directive, import statements, or other top-level declarations that they are intended to document.

2. Contextualize Comments: Every comment should have a clear context. It should be positioned immediately before the code it describes. This establishes a direct link between the comment and the code, eliminating ambiguity.

3. Remove Orphaned Comments: If you remove or significantly change a piece of code, be sure to review and update or remove the corresponding comments. Orphaned comments, those that no longer relate to existing code, become dangling comments and can mislead developers.

Example of a Dangling Comment (Problem):

Dart

// This comment is dangling! It's at the top of the file but doesn't clearly relate to anything yet.
// It's unclear what it's supposed to be documenting.

import 'package:flutter/material.dart';

// This class is now what the top comment might have been intended for.
class MyWidget extends StatelessWidget {
  // ...
}

Example of Correct Comment Placement (Solution):

Dart

/// This library provides widgets for displaying user profiles.  (Library level documentation)
library user_profile_widgets;

import 'package:flutter/material.dart';

/// A widget that displays a user's profile picture and information. (Class level documentation)
class MyWidget extends StatelessWidget {

  /// Builds the widget's layout. (Method level documentation)
  @override
  Widget build(BuildContext context) {
    // ...
  }
}

Here is another example;

Also; some contribution to fixing the same on github open source