# Commenting guidelines

<!--
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
Exceptions. See /LICENSE for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-->

These commenting guidelines are complementary to the
[evolution process](evolution.md). 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](/CODE_OF_CONDUCT.md) 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](goals.md)?
-   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?