feat(wbfy): generate a comment policy that forbids restating the code - #1329
Conversation
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request updates the coding style guidelines generated by wbfy to reduce documentation bloat. By mandating that comments only explain 'why' rather than 'what', the changes ensure that JSDoc and inline comments provide actual value rather than redundant information. This policy is applied conditionally based on repository visibility, ensuring that public npm packages retain necessary documentation for external consumers while private codebases remain clean and focused on code-level self-documentation. Highlights
New Features🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. The code is clear, the names are bright, No need to state what's in plain sight. If types and names tell all the tale, Then redundant comments must surely fail. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the agent coding style instructions in packages/wbfy/src/generators/agents.ts to include more specific guidance on JSDoc and comments, particularly regarding public npm registry packages. The review comment suggests improving the readability of the long prompt strings by splitting them across multiple lines in the source code, which is a valid improvement for maintainability.
| // Only public repositories publish packages to the public npm registry, whose users read the | ||
| // JSDoc without the source; private repositories are read only by agents that have the source. | ||
| const npmApiException = rootConfig.isPublicRepo | ||
| ? ' Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source.' | ||
| : ''; | ||
| const commentInstruction = `- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., \`@param name The name\`, \`@returns the result\`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as \`timeoutMs\`, a type, an \`assert\`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch.${npmApiException}`; |
There was a problem hiding this comment.
The prompt instruction string commentInstruction and its exception npmApiException are extremely long (over 800 characters on a single line), which makes the TypeScript source code difficult to read and maintain.
We can improve readability by splitting these long strings across multiple lines in the source code using backslashes (\) to escape the newlines. This keeps the compiled output as a single continuous line (without introducing actual newlines in the generated markdown) while keeping the source code clean and readable.
// Only public repositories publish packages to the public npm registry, whose users read the
// JSDoc without the source; private repositories are read only by agents that have the source.
const npmApiException = rootConfig.isPublicRepo
? ' Exception: the exported API of a package published to npm may carry JSDoc describing \
what it does and how to call it, because its users read it without the source.'
: '';
const commentInstruction = `- Comments and JSDoc: every reader has the source, so never restate what the code, \
its names, or its types already say (e.g., \\`@param name The name\\`, \\`@returns the result\\`, a narration of the control flow). \
Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge \
and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code \
(a name such as \\`timeoutMs\\`, a type, an \\`assert\\`, a test) and comment only what cannot be encoded: a deliberately \
odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with \
another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, \
so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in \
files you touch.${npmApiException}`;There was a problem hiding this comment.
Keeping the single-line literal. Long instruction strings in this file are already written on one line (e.g. the self-hosted runner instruction above), oxfmt does not wrap template literals, and backslash line continuations inside a template literal are easy to break when editing (a trailing space after the backslash changes the emitted text). The rendered rule is reviewed in the generated AGENTS.md, not in this source line.
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
1 participant
Why
The generated Coding Style told agents to write comments "only for hard-to-understand code" with "what" in JSDoc, which still lets JSDoc restate signatures and types. Every reader of a private WillBooster repository has the source, so such text is a second copy that must be kept in sync with the code for nothing. The new rule states when a comment is worth writing in terms of what breaks without it, mirroring the existing test rule, so the policy does not merely shift bloat from "what" to "contracts".
Requirements
assert, a test).Customer Summary
AGENTS.mdand its sibling files generated by wbfy now tell agents never to restate the code in comments or JSDoc, when a comment is worth writing, where to put it (JSDoc for a symbol's contract, inline for specific lines), and to delete comments that fail the test in files they touch. Public repositories additionally allow JSDoc on the exported API of npm-published packages.Technical Summary
generateAgentCodingStyleinpackages/wbfy/src/generators/agents.tsbuilds the rule fromrootConfig.isPublicRepo, replacing the previous single line. This repository's own generated instruction files (AGENTS.md,CLAUDE.md,GEMINI.md,.cursor/rules/general.mdc,.gemini/styleguide.md) are regenerated in the same PR so they carry the new rule. The matching review and simplification criteria are in WillBooster/agentic-workflows#685 and WillBooster/review-booster#338.Testing
bun run verifypassed. The generated instruction files were produced by running the local wbfy build on this repository; the unrelated dependency bumps that run also proposed were left out.