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.

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

You can edit comments, but you cannot delete 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.

By default, the Changes tab shows differences inline. If you prefer to see them next to each other, click the Side by side option at the top right of the tab. [HTH-1212] You can also hide whitespace differences by selecting the Ignore whitespace changes check box.

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

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.
(Optional) Click the Preview link to see what the comment will look like when submitted. To continue editing, click the Editor link.
Click Comment to submit your comment.

Formatting comments

Use Markdown syntax to format your comments.

Inserting emoji

Comments support emoji.

You can insert an emoji by:

Typing emoji code surrounded by colons
Using the emoji picker popup, either in a comment, a reply to a comment, or as a reaction to a comment

To insert emoji manually:

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

To insert emoji from the emoji picker:

Do one of the following:
- In the comment field, click the emoji icon at the bottom-right to open the emoji picker popup.
- To react to an existing comment, move the pointer over the comment to display the emoji icon on the right. Then click the icon to open the emoji picker popup.
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.
Select an emoji and click anywhere outside of the emoji picker to close the popup.

Inserting attachments

TeamHub lets you add attachments to a comment or response.

To add an attachment:

In the comment field, click the paperclip icon in the bottom right.
In the Open dialog, browse to the file you want to attach and click Open.

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:

To reply to a comment:

Click the Reply link below the comment. If a comment already has replies, the link is available under the last reply.
In the text field that opens, enter your response. The field is identical to the comment creation form, letting you insert text as well as emoji and attachments.
Click Reply.

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.

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.

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.

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.

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).