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.
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.
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.
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.
Use Markdown syntax to format your comments.
Comments support emoji.
You can insert an emojii by:
- Typing emoji code surrounded by colons
- Using the emoji picker popup
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
Enterto select an emoji, or press
Escto dismiss the popup.
To insert emoji from the emoji picker:
- Click the emoji icon at the bottom-right of the text area 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.
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.
- 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.
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).