From e1d16f9867c9097804d8f4baf3893cc49c19a2f6 Mon Sep 17 00:00:00 2001 From: ferran Date: Tue, 12 May 2026 15:26:15 +0200 Subject: [PATCH] [Docs] Prevent MDL codes in comments - Replaced the permissive "feel free to include MDL-12345" guidance with an explicit guidance not to use MDL codes in standard inline comments. - Tightened the TODO section: added "A TODO without an MDL code is invalid." to track the work that still needs to be done. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- general/development/policies/codingstyle/index.md | 8 ++++++-- general/development/process/peer-review/index.md | 2 ++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/general/development/policies/codingstyle/index.md b/general/development/policies/codingstyle/index.md index 202b6aac5..855b1587e 100644 --- a/general/development/policies/codingstyle/index.md +++ b/general/development/policies/codingstyle/index.md @@ -1913,11 +1913,15 @@ function forum_get_ratings_mean($postid, $scale, $ratings = null) { -If your comment is due to some MDL issue, please feel free to include the correct MDL-12345 in your comment. This makes it easier to track down decisions and discussions about things. +:::note + +Do not include MDL tracker references in standard inline comments (except in TODO comments, which must include a tracker reference). Inline comments should explain the logic and purpose of the code, not historical tracker context. + +::: #### Using TODO -This is especially important if you know an issue still exists in that code that should be dealt with later. Use a TODO along with a MDL code to mark this. For example: +This is especially important if you know an issue still exists in that code that should be dealt with later. Use a TODO along with an MDL tracker reference to mark this. A TODO without an MDL tracker reference is invalid. For example: diff --git a/general/development/process/peer-review/index.md b/general/development/process/peer-review/index.md index 103193314..e3a37b367 100644 --- a/general/development/process/peer-review/index.md +++ b/general/development/process/peer-review/index.md @@ -208,6 +208,8 @@ Work does not stop when code is integrated. Ensure that: - The PHPdoc comments on all classes, methods and fields are useful. (Comments that just repeat the function name are not helpful! Add value.) +- Standard inline comments do not include MDL tracker references and should focus on explaining logic and intent. +- Every TODO comment includes a corresponding MDL issue code to track the work that still needs to be done. - Where an API has been changed significantly, ensure that [upgrade notes](../upgradenotes) have been written (or upgrade.txt on older branches). - Where something has been deprecated, that the comments don't just say "do NOT use this any more!!!" but actually follow the [deprecation policy](../../policies/deprecation/index.md). - Appropriate [labels](../../tracker/labels.md) have been added when there has been a function change, particularly