From 93f818c4198e9e1f4c8b35efd95abfe5624f1999 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. --- 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..b9be78420 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 issue codes in standard inline comments. 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 a MDL code to mark this. A TODO without an MDL code is invalid. For example: diff --git a/general/development/process/peer-review/index.md b/general/development/process/peer-review/index.md index 103193314..045718e4b 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 code comments does not include MDL tracker references and 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