Copilot commented on code in PR #13931: URL: https://github.com/apache/trafficserver/pull/13931#discussion_r4405303760
########## AGENTS.md: ########## @@ -295,6 +295,18 @@ SMDebug(dbg_ctl, "Processing request for URL: %s", url); - This includes `.cc`, `.h`, `.py`, and other code files - Follow the existing license header format used in the codebase +### Comments Review Comment: The “Comments” section is duplicated verbatim in AGENTS.md and .claude/CLAUDE.md, which risks the two drifting over time. Consider making one file the source of truth and linking to it from the other (or adding a note that the section must be kept in sync) to reduce future maintenance burden. ########## AGENTS.md: ########## @@ -295,6 +295,18 @@ SMDebug(dbg_ctl, "Processing request for URL: %s", url); - This includes `.cc`, `.h`, `.py`, and other code files - Follow the existing license header format used in the codebase +### Comments +In general, comments should explain "why" and not "what"; no narration, +restated signatures, review-round residue, tracker tags or agent names, and +never previous behavior — what the code used to do and why it changed go in +the PR and commit message. Functions and classes should state their +responsibilities and the semantics of the variables - do not restate the type +of the variable. For instance, "Returns a std::string" is worse than useless - +the reader of the code can see the return type. Explain what the string is and +means in the context of its use in the codebase, such as "Returns the parsed +URL", for example. These comment instructions apply to the whole code base, +including production code, tests, Python, CMake and replay YAML files. + Review Comment: This paragraph contains a sentence fragment and a few readability/grammar issues that make the guidance easier to misread (e.g., “no narration,” lists without a verb; “commit message” singular; hyphen used as a dash in “variables - do not…”). Consider rewriting as full sentences and/or a short bullet list, and standardizing punctuation (e.g., use an em dash) so the rules are unambiguous. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
