Skip to content

Commit fac7291

Browse files
ferranrecioCopilot
andcommitted
[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>
1 parent e1d07bc commit fac7291

2 files changed

Lines changed: 8 additions & 2 deletions

File tree

general/development/policies/codingstyle/index.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1913,11 +1913,15 @@ function forum_get_ratings_mean($postid, $scale, $ratings = null) {
19131913

19141914
</InvalidExample>
19151915

1916-
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.
1916+
:::note
1917+
1918+
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.
1919+
1920+
:::
19171921

19181922
#### Using TODO
19191923

1920-
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:
1924+
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:
19211925

19221926
<ValidExample>
19231927

general/development/process/peer-review/index.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,8 @@ Work does not stop when code is integrated.
208208
Ensure that:
209209

210210
- The PHPdoc comments on all classes, methods and fields are useful. (Comments that just repeat the function name are not helpful! Add value.)
211+
- Standard inline comments do not include MDL tracker references and should focus on explaining logic and intent.
212+
- Every TODO comment includes a corresponding MDL issue code to track the work that still needs to be done.
211213
- Where an API has been changed significantly, ensure that [upgrade notes](../upgradenotes) have been written (or upgrade.txt on older branches).
212214
- 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).
213215
- Appropriate [labels](../../tracker/labels.md) have been added when there has been a function change, particularly

0 commit comments

Comments
 (0)