Commenting in code reviews

Comments are a way to collaborate on code reviews. They allow team members and external collaborators to discuss code reviews, request changes, suggest solutions, and so on.

Example of a comment thread

TeamHub organizes discussions in threads. For details, see Replying to Comments.

You can edit comments, but you cannot delet them.

Users watching the CR receive email notifications about new comments and replies.

On the Changes tab of a code review, you can comment on specific lines of code, letting involved parties scope their discussions to specific fragments of code. For details, see Code Line Comments.

You can use comments as tasks to indicate that some work has to be done before a code review should be merged. For details on this feature, see Tasks.

Reading comments

You can see comments on the Discussion tab of a code review.

The Discussion tab

The tab lists comments along with other types of activity, such as commits and approvals. Comments appear chronologically, with newer comments at the bottom of the list. Replies appear grouped under respective parent comments, sorted chronologically.

Creating comments

To create a new code review comment, do the following:

  1. Type your comment in the text field at the bottom of the Discussion tab. As you type, the Preview link becomes available below the field.
  2. (Optional) Click the Preview link to see what the comment will look like when submitted. To continue editing, click the Editor link.

    Previewing a comment that is about to be created

  3. Click Comment to submit your comment.

    Creating a comment

Formatting comments

Use Markdown syntax to format your comments.

Previewing markdown formatting

Inserting emoji

Comments support emoji.

A comment with emoji

You can insert an emojii by:

To insert emoji manually:

  1. Type a colon and at least two characters of an emoji code, for example :fo. An autocomplete popup appears. You can keep typing to narrow down the list of emoji.
  2. Select an emoji with the mouse pointer or keyboard. You can tab and shift-tab to navigate the list, press Enter to select an emoji, or press Esc to dismiss the popup.

    The emoji autocomplete popup

To insert emoji from the emoji picker:

  1. Click the emoji icon at the bottom-right of the text area to open the emoji picker popup.
  2. Browse all available emoji or filter the list using the text field at the bottom. The colored circles at the bottom right of the emoji picker popup allow changing the skin color of anthropomorphic emoji. It has no effect on the round-face smileys.
  3. Select an emoji and click anywhere outside of the emoji picker to close the popup.

    The emoji picker

Replying to comments

Each comment that you create via the comment form starts a new thread.

When you want to reply to a comment, do not create a new one. Instead, create a reply to the comment that you want to respond to. This lets the team have structured conversations, with unrelated matters kept separate:

Two threads discussing unrelated matters

To reply to a comment:

  1. Click the Reply link below the comment. If a comment already has replies, the link is available under the last reply.
  2. In the text field that opens, enter your response. The field is identical to the comment creation form.
  3. Click Reply.

Replying to a comment

Editing comments and replies

You can edit a comment or a reply by clicking the pencil icon.

The icon is visible in the top-right corner of a comment when you hover your mouse pointer over the comment.

Editing a reply

Deleting comments and replies

You cannot delete comments and replies. This is an intentional limitation aimed to prevent loss of information.

You can mark a comment as outdated, for example by applying formatting such as strikethrough or any other way you find reasonable. We recommend against editing out the text of outdated comments.

A striken-through comment

Email notifications

Users subscribed to the code review receive email notifications about new comments, along with other types of activity in a code review. Emails contain links to respective comments.

See Notifications for more info.

Code line comments

On the Changes tab of a code review, you can comment on individual lines of changesets. This is a convenient way to discuss code contributions, request changes, or suggest workarounds.

To create a line comment, hover the mouse pointer over a code line and click the comment button to the left.

Starting a new line comment

Line comments behave just like normal comments: They are listed on the Discussion tab, you can reply to them, and so on.

You can start multiple comment threads per line. They will be grouped together on the Discussion tab under the same line of code. As a result, a new line comment may not appear at the bottom of the activity list, as you might expect as per chronological order.

Two comment threads to same line of code on the Discussion tab

When the source files are updated, line comments may become outdated: They are attached to lines that are no longer part of the code review. Outdated line comments disappear from the Changes tab, but you can still access them on the Discussion tab, where they are available in a collapsed view.

You cannot comment on lines that are not part of the code review. However, you can reveal such lines by clicking the expand button).

Updated on: 19 December 2017