carbon-lang/docs/project/commenting_guidelines.md

Commenting guidelines

These commenting guidelines are complementary to the evolution process. The community comments on proposals when the proposal's status is "RFC", providing both positive and critical feedback. We always try to keep feedback, even when critical, constructive and supportive.

Guidelines

• Comments should be specific about the issue. They should include a suggested action, and the expected result from that action. The more specific a comment is, the easier it will be for the proposal author to evaluate.

  • Objections to specific phrasing should suggest alternative phrasing.

• Prefer GitHub for comments. When reviewing a proposal, we would like to keep the discussion focused in one place: the GitHub pull request.

  • If your comment represents a significant change to the proposal, include a list of advantages and disadvantages. Even if the author disagrees with the change, they can use those to document the alternative.
  • Feel free to extract long side discussions to a Discourse Forum topic, but make sure any important conclusions or outcomes are reflected in either the GitHub comments or the change itself.

• Be supportive in your criticism. The author may be receiving many comments, and we want to keep contributors motivated to respond.

• Be thoughtful about interactions. Keep the code of conduct in mind. Try to understand disagreements, and if you can't make progress, step back and think about other possible approaches.

• Compliment the author when you're happy with a proposal. Especially on the Discourse Forum topics where others will see the feedback. This helps all of us avoid only focusing on how proposals should improve. We want to balance that important feedback with explicit and positive feedback for all the good aspects.

When commenting on a proposal, some questions community members might want to address are:

• What is your evaluation of the proposal?
• Is the problem being addressed significant enough to warrant a change to Carbon?
• Does this proposal fit with Carbon's goals, priorities, and principles?
• Are there alternative approaches that may be better suited to the problem?
• If you have used other languages or libraries with a similar feature, how does the proposal compare?