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 Emoji emoticons, see Comment features for details.

You can add comments to:

• A changelist, review, or job
• A changelist or review 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 changelist or review description

1. From the changelist or review page description area: click Add a Comment or X Comments (where X 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 X Comments (where X is the number of description comments that exist). To display the comments again, click X 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. 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. 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 link.

2. Edit the comment content, including adding new attachments or removing existing attachments.

   When you remove an attachment, the attachment is marked for removal, the green bar for the attachment is muted, and the X button is replaced with a Restore button .

   Tip

   Click the Restore button to the right of the attachment to keep the attachment on the comment.

   Attachments cannot be restored after the comment edit has been saved. In this case you must edit the comment again and add the attachment to it.

3. Click Save to save the edited comment and remove any attachments marked for removal. The comment timestamp is marked as (edited) to show that the comment has been changed. Swarm sends a notification to everyone involved in the review, including the review author and the reviewers, but not the editor of the comment.

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 Flag button in the upper right of an existing comment and select Flag as 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.
• Not a 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 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: 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 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 list

A summary of the number and status of comments flagged as tasks is displayed below the code review description. Archived comments that are flagged as tasks are not included in the summary.

Click the Task list button to display a dialog listing all 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:

• 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 view a particular task, select the task in the Tasks dialog, and click the View button. Alternately you can double-click on the task in the Tasks dialog. The Tasks dialog closes and Swarm adjusts the review display so that the chosen task is in view.

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 Approve or, Approve and Commit a review that has open tasks with Swarm, 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 (X) button to the right of the comment box.
   Where (X) 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 (X) button, click the Send All Notifications button below your avatar on the review page to send all of the 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 (X) or Send All Notifications.

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 on the Reply link below the comment you are replying to.
2. Add your comment in the text area.
3. Click Post.

Emoji

Swarm comments support Emoji short-hand; when you save a comment, emoticon text like :smile: is displayed as: . Hover your mouse over an Emoji emoticon to see a tooltip displaying the text short-hand for the emoticon:

For more information on Emoji, see Emoji on Wikipedia. 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.

Comment attachments

Arbitrary files can be attached to comments. This is useful for sharing documents that are helpful in code reviews, such as screenshots of error conditions, reference code, etc.

To attach a file to an open comment:

1. Drag the file from your file browser and drop it on the comment area.

Multiple files can be attached to a comment, either one at a time, or by dragging a group of files. Folders cannot be attached to comments.

2. The upload to Swarm starts immediately and progress is displayed below the comment.
• Blue Progress Bar: the upload to Swarm is in progress.
• Green File Bar: upload complete.
3. If you attach a file to the comment by mistake, you can remove it by clicking the X button on the Green File Bar.
4. Click Post.

The filename and file size is displayed in the comment for each attached file, click on the filename to view the file.

When comments are viewed in the Comments tab, image previews are displayed for the attached images.

Liking comments

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

When you like a comment, a notification is sent to the author of the comment , and the heart icon changes to red to indicate that you have liked the comment . The number of likes the comment has is displayed next to the heart 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 heart icon again to unlike a comment.

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 at the top right of a posted 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 Mark all comments read button in the review heading.
2. All of the comments in the review are rolled up into single lines to save space.

Tip

Mark all comments read will mark all the comments as read including the description comments.

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 Mark comment as unread 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 Mark all comments unread button in the review heading.
2. The content of all of the comments in the review are expanded.
Tip

Mark all comments unread will expand the content of all the comments including the description comments.

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 button is only available for top level comments, if a comment has replies they are archived with the parent comment.

To archive a comment:

• Click the Archive button at the top right of a posted comment.

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.

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

Restore comments

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

To restore archived comments:

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.