Comments

Comments are the primary feedback mechanism provided by Swarm. Review comments can be flagged as tasks for a lightweight workflow within a review that helps authors and reviewers prioritize review feedback, see Tasks for details. By default, comment notifications are delayed to allow you to add or edit comments as you progress through a review without sending a notification for each individual comment on the review. Comment notifications are rolled up into a single notification that you can either leave to be sent automatically, or you can send manually, see Comment notification delay.

You can also like comments, add links, add attachments, and add Emojis, see Comment features for details.

You can add comments to:

• A changelist, review, or job
• A review description
• A changelist description
• A line of a text file in a changelist, or review
• A file in a changelist, or review

Access comments for a changelist, review, or job, by clicking the Comments tab. The number of open (non-archived comments) is displayed in the tab. Hover your mouse pointer over the comment count, the tooltip shows how many comments are archived. See Archiving comments for details.

Adding comments

This section describes how to add comments.

Related comment features:

• Comment notification delay
• Reply to comment
• Emoji
• Links
• Attachments
• Markdown

Commenting on a changelist, review or job

1. From the changelist, review, or job page: click Comments to view the Comments tab.
2. Add your comment in the text area.
3. Click Post.

Commenting on a review description

1. From the changelist or review page description area: click Comments (n) (where n is the number of comments that already exist).
2. Click Add a comment.
3. Add your comment in the text area.
4. Click Post.
Tip

To hide the description comments, click Comments n (where n is the number of description comments that exist). To display the comments again, click Comments n.

Commenting on a changelist description

1. From the changelist or review page description area: click Add a Comment or n Comments (where n is the number of comments that already exist).
2. Add your comment in the text area.
3. Click Post.
Tip

To hide the description comments, click n Comments (where n is the number of description comments that exist). To display the comments again, click n Comments.

Commenting on a specific line in a file in a changelist or review

1. From the changelist or review page: click Files to view the Files tab.
2. Click on the line you want to comment on.
3. Add your comment in the text area.
4. Optional (Review page only): Select the Flag as Task checkbox to mark the comment as a task that needs to be addressed.
5. Click Post.

Commenting on a file in a changelist or review

1. From the changelist or review page: click Files to view the Files tab.
2. If there are multiple files, click the file you want to comment on to expand its view.
3. Click the Add a comment link in the footer of the file display.
4. Add your comment in the text area.
5. Optional (Review page only): Select the Flag as Task checkbox to mark the comment as a task that needs to be addressed.
6. Click Post.

Editing comments

This section describes how to edit comments.

Related comment features:

• Comment notification delay
• Reply to comment
• Emoji
• Links
• Attachments
• Markdown

1. Click the comment Edit comment link.

2. Edit the comment text.

3. Add attachments or remove attachments. For instructions on adding and removing attachments, see Comment attachments.

   Tip

   If you remove the wrong file attachment but have not saved the comment yet, click Cancel, and the file will remain attached to the comment.

4. Click Save to save the edited comment.

   Swarm sends a notification to everyone involved in the review, including the review author and the reviewers, but not the editor of the comment.

   The comment timestamp is marked as (edited) to show that the comment has been changed.

Tasks

Flagging review comments as tasks is a lightweight workflow within a review that helps authors and reviewers prioritize review feedback. Any comment on a code review can be flagged as a task, indicating to the code review's author that the described issue needs to be addressed, and that the review is unlikely to be approved without a fix.

Flag a comment as a task

To flag a comment as a task, select the Flag as Task checkbox when posting a comment, or click the Comment actions button in the upper right of an existing comment and select Flag as Open task in the drop-down menu.

Set a task to Task addressed or Not a task

Once a comment is flagged as a task, it is considered to be an open task. Click the Red flag button to display a drop-down menu with the following options:

• Task addressed: usually used by the author of the review to indicate that the issue has been fixed.
• Remove task: used to correct comments that have been flagged as tasks by mistake.

Verify a task, verify and archive a task, or reopen a task

A comment with a green check indicates that the task has been addressed. Click the Green check mark button to display a drop-down menu with the following options:

• Verify task: usually used by the author of the comment, or another reviewer, after confirming that the issue is fixed.
• Verify and Archive (only supported in the original Swarm review page): used to both indicate that the issue has been fixed, and to archive the comment so that it is hidden from view. Archived tasks, whether they are open, addressed, or verified, are not included in the task counts for the code review.
• Reopen task: used if the issue needs further work after it has been marked as addressed.

Reopen a task

A comment with a blue double-check indicates that the task has been verified. Click the Blue double-check mark button to display a drop-down menu with the following option:

• Reopen task: used if the issue needs further work post-verification, or if verification was made by mistake.

Task details

A summary of the number and status of comments flagged as tasks is displayed in the Information panel to the right of the review.

• Red Flag: Displays the number of open tasks on the review.
• Green check mark: Displays the number of addressed tasks on the review.
• Blue double-check mark: Displays the number of addressed and verified tasks on the review.

Show Task details : Click to display a dialog listing all of the tasks associated with the review:

Within the Tasks dialog, you can filter the tasks by the Reporter (the userid of the user who created the task), and/or by task state using the buttons at the top of the dialog:

• Click the Red flag button to display only open tasks (comments that need to be addressed).
• Click the Green check mark button to display only addressed tasks (comments that have been addressed).
• Click the Blue double-check mark button to display only verified tasks (comments that have been addressed and verified).

To change the state of a task from the Tasks dialog, click the task state dropdown for the task and select the new task state.

To view the full comment text for a task, click the ellipses to the right of the task.

Approve a review with open tasks

Flagging a comment as a task provides a visual indication that there is an identified issue that needs to be addressed before the review can be approved, see Set a task to Task addressed or Not a task.

If you select Approve or Approve and Commit for a review that has open tasks, a warning message is displayed in the Update Review dialog. The warning is only advisory, either click Cancel and address the open tasks or click Approve to approve the review. Archived open tasks will not trigger the warning message.

Comment features

Comment notification delay

By default, comment notifications are delayed to allow reviewers to add or edit comments as they progress through a review without sending a notification for each individual comment on the review. Comment notifications are rolled up into a single notification and sent either manually by the reviewer, or automatically after the notification delay time has been exceeded.

The delay countdown is reset each time the reviewer adds or edits a comment on the review, by default the notification delay time is set to 30 minutes.

• If you are commenting on more than one review, each of the reviews that you are commenting on has its own notification delay countdown that only applies to the comments that you make on that review.
• If another reviewer is making comments on the same review as you, that reviewer has their own notification delay timer for that review.
• If you manually send a delayed comment notification, the notification will only contain the comments that you made on that review.

Manually send the comment notification immediately:

1. Add or edit your comment as normal.
2. Click the Post and notify (n) button to the right of the comment box.
   Where (n) is the number of delayed comment notifications in the queue waiting to be sent, this number does not include the current comment you are working on.
Tip
• If you forget to click the Post and notify (n) button, click the Send All Notifications (n) button below the review description to send all of your notification for the review immediately.
• Only the comments that you have made on this review are rolled up into the notification that is sent when you click Post and notify (n) or Send All Notifications (n).

Reply to comments

By default, you can reply to comments, replies are displayed in a thread below the parent comment. Comment thread depth is set to 4 by default, this means you can have up to 4 levels of replies for a parent comment. The Reply link is not displayed for replies at or above the maximum thread depth set for Swarm. If the parent comment is archived, replies are archived with the parent, see Archiving comments.

To reply to a comment:

1. Click Reply below the comment you are replying to.
2. Add your comment in the text area.
3. Click Post.

Emoji

Swarm comments support Emoji shorthand. So when you save a comment, emoticon text like :smile: is displayed as:

Emoji emoticons are listed in the Emoji Cheat Sheet.

Links in comments

Whenever you include a URL in a comment, it is automatically made into a link.

If the link points to an image, or a YouTube video, that resource is displayed at the end of the comment. For information about linking images and videos, see Common text styles.

Comment attachments

Files can be attached to comments. This is useful for sharing files in code reviews, such as screenshots of error conditions, reference code, and documents.

When a file is attached to a comment, you can:

• Hover over the attachment to see its filename and file size.

• Click the attachment to open the file in a new browser tab.

• Hover over the attachment and click the Download button to download the file.

Adding attachments to a comment

To attach a file to an open comment:

1. Do one of the following:
   • Drag the files from your file browser and drop them on the comment.

   If you drag a folder onto a comment, all of the files in the folder and the files in any subfolders are added to the comment.

   • Click Choose your files and select the files from the browse dialog.

   You cannot add folders to a comment using the file picker.

2. If you attach a file to the comment by mistake, you can remove it by clicking the X button on the attachment.
3. Click Post.

The file attachments are displayed below the comment text and image thumbnails are displayed for supported image formats.

Removing an attachment from a comment

1. Click the comment Edit comment link.

2. Hover over the attachment you want to remove and click X to remove the file.

3. Confirm you want to remove the attachment when prompted.

4. Click Save to save the comment.

Tip

If you remove the wrong file attachment but have not saved the comment yet, click Cancel, and the file will remain attached to the comment.

Reacting to comments

As an authenticated user, you can like a comment by clicking the thumbs up icon beneath the comment.

When you like a comment, a Notification is sent to the author of the comment, and the thumbs up icon changes to yellow to indicate that you have liked the comment. The number of likes the comment has is displayed next to the thumbs up icon. If a comment is edited, all of the likes for that comment are removed.

Hover your mouse pointer over the number of likes to display the usernames of everyone that has liked the comment.

Click the thumbs up icon again to unlike a comment. You can like/unlike a comment that has been archived.

Comment context

When comments are added to files in a review, on lines that have been changed, Swarm records several lines of context before the line receiving the comment. This helps makes sense of the comments should later changes remove those lines.

Each comment associated with that line has a record of the context, but only the first comment displays that context.

Mark comments as read

When you mark a comment as read, the comment is rolled up into a single line to save space and make it easier for you to find comments you have not read. The read flag is remembered independently for each user.

Mark a single comment as read:

1. Click the Mark comment as read button to the right of the comment.
2. The comment is rolled up into a single line to save space.



Note

Marking a parent comment as read will not mark the child comments as read.

Mark all of the comments on a review as read:

1. Click the Review actions button.
2. Select Mark all comments read from the dropdown menu.
3. All of the comments in the review are rolled up into single lines to save space.

Mark comments as unread

Marking a comment as unread expands the comment so that you can view the comment content. If a comment is marked as read and the comment changes, Swarm will automatically clear the read flag so that you can see that the comment has changed. Changes that automatically mark a comment as unread are:

• Comment text is edited
• Comment attachments are added or removed
• Comment is marked as a task
• Task is reopened
• Comment or task is unarchived

Mark a single comment as unread:

1. Click the button to the right of the comment.
2. The comment content is expanded.
Note

Marking a parent comment as unread will not mark the child comments as unread.

Mark all of the comments on a review as unread:

1. Click the Review actions button.
2. Select Mark all comments unread from the dropdown menu.
3. The content of all of the comments in the review are expanded.

Archiving comments

As a code review progresses, comments made on earlier versions of a file might become less useful. Archiving these comments tidies up the comment view and makes it easier to find the more important comments.

The Archive option is only available for top level comments, if a comment has replies they are archived with the parent comment.

To archive a comment:

1. Click the Comment actions button at the top right of the comment you want to archive.

2. Select Archive from the dropdown menu.

Archived comments are hidden from view, the number of archived comments that exist for the review is displayed in the archived comments button at the top of the Comments tab.

To display and hide archived comments:

Click on the archived comments button to toggle the archive comment display on and off.

Restoring comments

Archived comments can be restored. If archived comments have replies, the replies are also restored.

To restore an archived comment:

1. Click the archived comments button at the top of the Comments tab to display all of the archived comments.



2. Find the comment you want to restore.
3. Click the Restore button in the top right of the comment to restore it.