add tear-off doc to `prefer_constructors_over_static_methods`

[pq]

Current doc (here)

PREFER defining constructors instead of static methods to create instances.

In most cases, it makes more sense to use a named constructor rather than a
static method because it makes instantiation clearer.

BAD:

class Point {
  num x, y;
  Point(this.x, this.y);
  static Point polar(num theta, num radius) {
    return Point(radius * math.cos(theta),
        radius * math.sin(theta));
  }
}

GOOD:

class Point {
  num x, y;
  Point(this.x, this.y);
  Point.polar(num theta, num radius)
      : x = radius * math.cos(theta),
        y = radius * math.sin(theta);
}

@srawlins: can you elaborate on what you had in mind for updating the docs?

[srawlins]

I wonder if there is an example that might be a clear reference to Flutter (if I understand correctly, the primary motivator for the feature). But otherwise, something like:

"With the new Constructor Tearoffs feature, constructors can be torn off and passed as values to be invoked indirectly." But I don't have any examples that might have motivated the feature.

[pq]

I wonder if there is an example that might be a clear reference to Flutter

/cc @goderbauer @lrhn

[lrhn]

As long as the lint doesn't make you introduce a public generative constructor on a class which doesn't already have one, I think it's a fine suggestion, but there are exceptions. It's not a lint I'd enable myself, I'd fear false positives.

For example, the parse functions have generally been static methods, not constructors. That's because named constructors are named using descriptions of the instance being created (List.filled, String.fromEnvironment) and methods are named using verb phrases (int.parse). A constructor named int.parse would be wrong, and int.fromString would be "more correct".

So, it's not just a trivial "this static method returns the same type as the class, so it should be a constructor" rule. You have to change the name if you change the implementation. You might want to make it a factory constructor (since it's already a method, that's the easiest migration).

If the method has different type bounds than the class, you can't just move it over to a constructor (Consider a static List<E> sorted<E extends Comparable<E>>(Iterable<E>) => ... on List - it's named like a constructor, and should be a constructor, but you can't restrict the type arguments in a constructor ... sadly.)

The point example is actually good. The polar is named like a constructor and does minimal computation, so it really fits as a constructor.

[pq]

Thanks @lrhn, all!

I'm not seeing a good motivating example to add to the docs calling out tear-offs so I'm going to close this.

Feel free to re-open if anyone wants to continue the conversation?