Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions general/development/policies/codingstyle/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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.

:::

Expand Down
Loading