Comments

Comments are the primary feedback mechanism provided by Swarm. Comments can be made on files in a review, on any lines of any text file in a review, and on jobs.

Tasks

Flagging 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 a code review's author that the described issue needs to be addressed, and that the review is unlikely to be approved without a fix.

Drop-down menu for flagging a comment as a task. The Flag as Task checkbox. To flag a comment as a task, check the Flag as Task checkbox when posting a comment, or click the flag icon in the upper right of an existing comment and select Flag as Task in the drop-down menu.

Note

If you do not have permission to archive comments, you do not have permission to flag comments as tasks. Anonymous users never have permission to archive comments, and can only view current task states.

Drop-down menu for open tasks. Once a comment is flagged as a task, it is considered to be an open task. Clicking the red flag icon displays a drop-down menu with the following options:

  • Task Addressed: usually used by the review's author to indicate that the noted issue has been fixed.

  • Not a Task: used to correct comments that have inappropriately been flagged as tasks.

Drop-down menu for addressed tasks. A comment with a green check indicates that the task has been addressed. Clicking the green check displays a drop-down menu with the following options:

  • Verify: usually used by the comment author, or other reviewer, after checking that the issue is indeed fixed.

  • Verify and Archive: used to both indicate that the issue has been fixed, and to archive the comment so 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 when an update to the review does not resolve the noted issue, or to correct an inadvertant task verification.

Drop-down menu for verified tasks. A comment with a blue double-check indicates that the task has been verified. Clicking the blue double-check displays a drop-down menu with the following option:

  • Reopen Task: used if the issue needs further work post-verification, or if verification was made inadvertently.

Task counts/status summary. A summary of comments flagged as tasks and their various states appears below the code review's description, beside the reviewers area. Archived comments that are flagged as tasks are not included in the summary.

Like many of Swarm's features, tasks are merely advisory. Flagging a comment as a task provides visual indication that there is an identified issue, but Swarm does not restrict any operations for tasks in any state. A warning is displayed should you attempt to approve or commit a review via the Swarm UI that has any open tasks (that are not archived):

A warning about open tasks when approving a review.

Comment features

Emoji

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

Tip

For more information on Emoji, see Emoji at Wikipedia. Emoji emoticons are listed in the Emoji Cheat Sheet.

Comment attachments

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

The Comment area when attachments are enabled. Swarm must be configured to enable comment attachments. Once the configuration is complete, the comment area adds a note Drop files here to attach them.

To attach a file, simply drag it from your desktop or file browser and drop the file onto the comment area. Multiple files can be attached to a comment, either one at a time, or by dragging a group of files in one go. However, uploading a folder of files is not supported.

When you let go of the file (or files), the upload to Swarm starts immediately, and a progress bar for each file is displayed below the comment area with green bars indicating completed uploads and blue bars indicating uploads in progress:

The Comment area with attachments progress bars.

Before you post your comment, if any files already attached should be removed, click the X to the right of the attached file you wish to remove.

After you post your comment, a list of attached files appears below the comment text. The list includes the filename and file sizes for each attached file. When you view your comment on the Comments tab, Swarm displays an image preview for any attached images.

A comment with its attached files.

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.

Commentary on a change, showing its context.

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

Commenting on a changelist or review

  1. Visit the changelist's or review's page.

  2. Comments tab on Reviews page Click Comments to view the comments tab.

  3. Comment area for a review Add your comment in the provided text area.

    Also see “Comment attachments” above.

  4. Post button Click Post.

Commenting on a specific line in a file

  1. Visit the changelist's or review's page.

  2. Files tab Click Files to view the file tab.

  3. Click a line you want to comment on. The comment text area appears.

  4. Comment area in a diff Add your comment in the provided text area.

  5. Post button for Comments Click Post.

Commenting on a file in a changelist or code review

  1. Visit the changelist's or review's page.

  2. Files tab Click Files to view the file tab.

  3. If there are multiple files, click the file you want to comment on to expand its view.

  4. The link to add a comment to a file. Click the Add a Comment link in the footer of the file's display.

  5. Comment area in a diff Add your comment in the provided text area.

  6. Post button for Comments Click Post.

Note

You can use “@mentions” in comments. An @mention includes the specified user in the review, and they will receive a notification whenever there is an update to the review.

Archiving comments

As a code review progresses, comments made on earlier versions of a file may no longer be pertinent. If left unattended, comments may accumulate until it is difficult to determine which comments are still relevant and which comments have been addressed.

  1. The Comment Archive button Click the file drawer icon at the top right of a posted comment to archive it.

Archived comments are normally hidden from view. When archived comments exist, a box appears showing the number of archived comments. Click the box to toggle the presentation of all archived comments.

The Archived Comments box

Restore comments

A closed comment may be restored.

  1. Click the archived comments box to display all archived comments.

  2. Locate the comment you want to restore

  3. The Comment Restore button Click the arrow icon in the top right of the comment to restore it.