carbon-lang/docs/project/commenting_guidelines.md

Carbon: 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.

• Use Discourse Forums for long comments. If a Google Doc comment would be over two paragraphs, take it to the Discourse Forum topic. Doc comments are good for quick, short feedback; detailed feedback is better shared on Discourse Forums.

  • Use the forum topic created by the author, rather than creating a new topic. It needs to be easy for authors and other reviewers to find comments.
  • If your comment represents a significant change to the doc, include a list of pros and cons. Even if the author disagrees with the change, they can use those to document the alternative.

• 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?