• Use comments to clarify the purpose of complex code segments. The code should be self-explanatory, but comments can provide additional context or explain intricate logic.
  • Document the purpose of functions, classes, and variables. Comments should explain the intent behind the code, focusing on the “what” and “why,” not the “how.”
  • Note any assumptions or constraints that the code depends on. This helps other developers understand the code’s context and conditions.
  • Highlight any known issues or limitations with the code. This guides other developers in navigating common challenges or limitations.
  • Maintain consistent comment formatting. For instance, adopt a uniform style for documenting function parameters, return values, and exceptions.
  • Refrain from commenting on obvious or trivial code. Comments should enrich the code, not overcrowd it with redundant information.
/// Computes the distance between two points in a Cartesian plane.
///
/// [pointA] and [pointB] are points with x and y properties.
/// Returns the Euclidean distance between [pointA] and [pointB].
///
/// Note:
/// This function assumes that [pointA] and [pointB] are maps with x and y keys.
/// It does not perform any error checking on the inputs.
double computeDistance({required Map<String, double> pointA, required Map<String, double> pointB}) {
  final dx = pointB['x']! - pointA['x']!;
  final dy = pointB['y']! - pointA['y']!;
  return sqrt(dx * dx + dy * dy);
}
By following these guidelines for commenting in Flutter, the codebase remains understandable, maintainable, and facilitates easier collaboration among developers.

Copy code