Explain non-obvious code

// Bad: No explanation for magic numbers or logic
class MaterialTextSelectionControls extends TextSelectionControls {
  @override
  Offset getHandleAnchor(TextSelectionHandleType type, double textLineHeight) {
    return switch (type) {
      TextSelectionHandleType.collapsed => const Offset(_kHandleSize / 2.18, -4.5),
      // ...
    };
  }
}

// Good: Clear explanations provided
class MaterialTextSelectionControls extends TextSelectionControls {
  @override
  Offset getHandleAnchor(TextSelectionHandleType type, double textLineHeight) {
    return switch (type) {
      // These values were eyeballed to match a physical Pixel 9 running Android 16,
      // which horizontally centers the anchor 1 pixel below the cursor.
      TextSelectionHandleType.collapsed => const Offset(_kHandleSize / 2.18, -4.5),
      // ...
    };
  }
}

// Bad: Unclear parameter purpose
void hideToolbar([bool hideHandles = true, Duration? toggleDebounceDuration]);

// Good: Parameter purpose documented
/// Hides the text selection toolbar.
///
/// By default, [hideHandles] is true, and the toolbar is hidden along with its
/// handles. If [hideHandles] is set to false, then the toolbar will be hidden
/// but the handles will remain.
///
/// When [toggleDebounceDuration] is non-null, a subsequent call to [toggleToolbar]
/// should not show the toolbar unless a duration threshold has been exceeded.
void hideToolbar([bool hideHandles = true, Duration? toggleDebounceDuration]);