Skip to content

MDLSITE-4789 Prevent MDL codes in comments #1594

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ferranrecio wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −2
Open

MDLSITE-4789 Prevent MDL codes in comments #1594

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
8 changes: 6 additions & 2 deletions general/development/policies/codingstyle/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1913,11 +1913,15 @@ function forum_get_ratings_mean($postid, $scale, $ratings = null) {

</InvalidExample>

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.
Copy link
Copy Markdown
Member

@paulholden paulholden May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as https://github.com/moodle/devdocs/pull/1594/changes#r3246858212 "MDL issue codes"


:::

#### 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:
Copy link
Copy Markdown
Member

@paulholden paulholden May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest using the same terminology as previously used in this PR, instead of "an MDL code" consider "an MDL tracker reference"


<ValidExample>

Expand Down
2 changes: 2 additions & 0 deletions general/development/process/peer-review/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading