From 2ba527b6963e58d32868ffc5c0621c453208adcc Mon Sep 17 00:00:00 2001 From: Andrew Nicols Date: Thu, 5 Nov 2026 22:49:16 +0800 Subject: [PATCH] [docs] Improve docs relating to documentation of overridden methods --- general/development/policies/codingstyle/index.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/general/development/policies/codingstyle/index.md b/general/development/policies/codingstyle/index.md index 9b8758847..16ce2881c 100644 --- a/general/development/policies/codingstyle/index.md +++ b/general/development/policies/codingstyle/index.md @@ -268,9 +268,7 @@ In the case of legacy functions (those not placed in classes), names should star Verbosity is encouraged: function names should be as illustrative as is practical to enhance understanding. -:::tip[Overriding parent methods] - -When writing a method which overrides a method in a parent Class, Interface, or Trait, it is strongly recommended that the `#[\Override]` attribute be used, for example: +When writing a method which overrides a method in a parent Class, Interface, or Trait, you should use the [`#[\Override]`](https://www.php.net/manual/en/class.override.php) attribute to indicate that the parent method is expected to exist. If the parent method is removed in a future change a compile-time error will be thrown alerting you to this fact. ```php title="Example of a method which overrides a third-party method" class example extends \Some\Vendor\ExampleClass { @@ -281,7 +279,13 @@ class example extends \Some\Vendor\ExampleClass { } ``` -In Moodle's coding standard, this attribute is also used by PHPCS rules as a signal that the method is a genuine override, so some sniffs relating to documentation and to the naming of the overridden method and its parameters are not applied. +In Moodle's coding standard, the `#[\Override]` attribute is also used by PHPCS rules as a signal that the method is a genuine override, so some sniffs relating to documentation and to the naming of the overridden method and its parameters are not applied. + +:::danger + +When documenting an overriding method, prefer the child method's more specific or useful documentation over vague, generic, or incomplete documentation from the parent method. + +If a patch provides useful documentation, advice should not be given to remove it unless it should be moved to the parent method. :::