Review main Merged

81422[TASK] Improve property type annotations for GraphicalFunctions

Oliver Klee CR +2 V +2 Easy +22 −4 updated 10/21/23, 12:45

Commit message

This is a pre-patch for adding more specific type annotations
to the methods in this class.

Review

  • Code review CR +2 Done
    • Christian Kuhn +2
    • Garvin Hicking +1
  • Verified V +2 Done
    • Christian Kuhn +2
    • Garvin Hicking +1
    • core-ci +1 CI

Issues 1

Files 1

Review log 1518

  1. Oliver Klee uploaded patch set 1 10/12/23, 16:10

  2. core-ci voted on patch set 1 V +1 10/12/23, 16:18 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47727

  3. Georg Ringer commented on patch set 1 10/13/23, 08:32

    GraphicalFunctions.php:44

    general questions: what is the real benefit for that and should we now change the whole core just to make phpstan more happy? why not using the type string and remove the var block completly?
  4. Oliver Klee commented on patch set 1 10/13/23, 08:55

    GraphicalFunctions.php:44 Reply

    More specific type annotations allow tools like PHPStan or Psalm to do more precise type analysis, for example: - complain if code tries to set this property to an empty string - in code that read this property, know that the property is a non-empty-string, and then complain that a `!== ‘’` check is redundant (as it’s always true) So it’s about helping coders write better code, not about the emotional state of a tool. ;-) And indeed adding more specific type annotations to existing code helps (even though there is no rush to do so).
  5. Oliver Klee commented on patch set 1 10/13/23, 12:22

    GraphicalFunctions.php:44 Reply

    Oh, and the type annotations are also for the benefit of the persons reading the code: They then know in this case that this property may and will never have an empty string.
  6. Oliver Hader commented on patch set 1 10/13/23, 12:43

    GraphicalFunctions.php:44 Reply

    This only would work for `private` properties - or in general, source code that is in full control of the component that holds these type hint clains. Example: * the `protected` property is overridden by some XClass and set to an empty string `''` * the default (non-extended) implementation would not know about that and omit any checks for empty strings * (side-note) in the current implementation the property could actually be anything during runtime, because that is not restricted on a language level by using `protected string $colorspace` Thus, before adding type-specific optimization, we should have type restrictions (e.g. using `string`) in place.
  7. Oliver Klee commented on patch set 1 10/13/23, 13:12

    GraphicalFunctions.php:44 Reply

    Is disagree. As far as I can see, neither (native type declarations and more specific type annotations) blocks the other.
  8. Oliver Klee commented on patch set 1 10/13/23, 13:21

    GraphicalFunctions.php:44 Reply

    Oh, and I agree that we should have both: native type declarations and more specific type annotations (where they add value).
  9. Oliver Klee rebased onto patch set 2 V +1 10/15/23, 14:23

  10. core-ci voted on patch set 2 V +1 10/15/23, 14:31 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47782

  11. Oliver Hader commented on patch set 2 10/16/23, 06:40

    GraphicalFunctions.php:44 Reply

    Hm, I did not write anything like "neither (native type declarations and more specific type annotations) blocks the other"?! I was referring to the consequences, of e.g. removing code like `!== ''` because PHPStan says it would always be true. Besides my written example, I always created that code-wise, to demonstrate why it even could be dangerous to blindly trust PHPStan suggestions and to remove code like `=== ''`. The scenario in that example would be different, in case the class property `$value` would be `private` instead of `protected`. Because then, it is guaranteed, that only the same class that produced the claim `$value always is non-empty-string` is solely in control (no other user-land code that might override the behavior).
  12. Oliver Hader commented on patch set 2 10/16/23, 06:42

    I don't want to block this effort - however, I had to point out, that the real benefits might be different (that was the initial question by Georg) and blindly trusting PHPStan might be dangerous - and of course that's the same for PsalmPHP as well...
  13. Oliver Klee commented on patch set 2 10/16/23, 08:57

    Reply

    Ah, I understand. Thanks for the additional explanation!
  14. Oliver Klee uploaded patch set 3 V +1 10/19/23, 08:09

  15. core-ci voted on patch set 3 V +1 10/19/23, 08:16 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47927

  16. Garvin Hicking commented on patch set 3 V +1 CR +1 10/20/23, 11:44

    I agree that especially phpdoc hints ease integration and documentation efforts. In this concrete patch those hints seem unproblematic. And it doesn't require that all code will immediately be enhanced, too. This could be an ongoing effort and reviewed on smaller fractions (like intended, I guess) to be sure that doc hints do not interfer with native hints, and they also take XClasses/(un)final/(un)internal modifications into account. TL;DR: +1 :-D
  17. Christian Kuhn voted on patch set 3 V +2 CR +2 10/21/23, 12:44

  18. Christian Kuhn merged patch set 4 10/21/23, 12:45