MDLSITE-4789 Prevent MDL codes in comments#1594
Open
ferranrecio wants to merge 1 commit into
Open
Conversation
- 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.
✅ Deploy Preview for moodledevdocs ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Moodle DevDocs guidance to discourage including MDL tracker codes in standard inline code comments, while reinforcing that TODO comments must be trackable via an MDL issue.
Changes:
- Adds peer-review checklist items to avoid MDL references in standard comments and require MDL codes for TODOs.
- Replaces “feel free to include MDL-12345” with an explicit “do not include MDL issue codes” admonition in the coding style policy.
- Tightens TODO guidance by stating that a TODO without an MDL code is invalid.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| general/development/process/peer-review/index.md | Adds checklist bullets covering MDL codes in comments and MDL-linked TODO requirements. |
| general/development/policies/codingstyle/index.md | Updates commenting guidance to prohibit MDL codes in standard inline comments and strengthens TODO/MDL tracking requirements. |
| 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. |
| #### 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: |
Member
There was a problem hiding this comment.
I'd suggest using the same terminology as previously used in this PR, instead of "an MDL code" consider "an MDL tracker reference"
paulholden
requested changes
May 15, 2026
| 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. |
Member
There was a problem hiding this comment.
Same as https://github.com/moodle/devdocs/pull/1594/changes#r3246858212 "MDL issue codes"
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
[Docs] Prevent MDL codes in comments