vscode-code-review

This extension allows you to create a code review file you can hand over to a customer.

---

• vscode-code-review
• Features
  • create review notes
  • export created notes as HTML
  • Export for Issue Tracking System
• Extension Settings
• Keybindings
• The review approach

---

Features

create review notes

Simply right click somewhere in the opened file and choose the option "Code Review: Add Note". You will be prompted for your note you wanna add. A file code-review.csv will be created containing your comments and the file and line references.

The result will look like this:

sha,filename,url,lines,title,comment,priority,additional
"b45d2822d6c87770af520d7e2acc49155f0b4362","/test/a.txt","https://github.com/d-koppenhagen/vscode-code-review/tree/b45d2822d6c87770af520d7e2acc49155f0b4362/test/a.txt","1:2-4:3","foo","this should be refactored","Complexity",1,"see http://foo.bar"
"b45d2822d6c87770af520d7e2acc49155f0b4362","/test/b.txt","https://github.com/d-koppenhagen/vscode-code-review/tree/b45d2822d6c87770af520d7e2acc49155f0b4362/test/b.txt","1:0-1:4|4:0-4:3","bar","wrong format","Best Practices",1,""

The line column indicates an array of selected ranges or cursor positions separated by a | sign. E.g. "1:0-1:4|4:0-4:3" means that the comment is related to the range marked from line 1 position 0 to line 1 position 4 and line 4 position 0 to line 4 position 3.

export created notes as HTML

Once you finished your review and added your notes, you can export the results as an HTML report. Therefore open the VSCode Command Palette (macOS: ⇧+⌘+P, others: ⇧+Ctrl+P) and search for "Code Review":

Default template

When you choose to generate the report using the default template, it will look like this in the end:

You can define a path to a custom template that's used by default when running this command. Check out the Extension Setting 'defaultTemplatePath' for further information.

Custom handlebars template

You can also choose to export the HTML report by using a custom Handlebars template. One you choose this option you cot prompted to choose the template file (file extension must be either *.hbs, *.handlebars, *.html or *.htm)

The used structure to fill the template placholders is an array of ReviewFileExportSection.

Check out the example default template file template.default.hbs, to see how your template should basically look like.

Export for Issue Tracking System

export created notes as GitLab importable CSV file

Once you finished your code review, you can export the results to a formatted csv file that's importable into Gitlab issues.

Once exported, you can import the file in the GitLab project

export created notes as GitHub importable CSV file

You can export the code review results to a formatted csv file that's importable into GitHub by using github-csv-tools.

export created notes as JIRA importable CSV file

You can also export the notes as a CSV file to import them into your JIRA issue tracking system.

After exporting, you can import the file in your JIRA instance and probably map the props / ignore what you don't need:

Extension Settings

The following settings can be adjusted via the configuration file .vscode/settings.json or globally when configuring vscode. The listing below shows the default configuration:

code-review.filename

The filename for the *.csv file that stores all comments. By default "code-review" is used.

{
  "code-review.filename": "my-review-file"
}

code-review.baseUrl

The base-URL is used to build a full link to the file. It will be appended with the git SHA if available followed by the relative path of the file and the selected lines as an anker. This setting is skipped when the setting code-review.customUrl is defined which is more configurable.

{
  "code-review.baseUrl": "https://github.com/foo/bar/blob"
}

This setting would lead into something like this: https://github.com/foo/bar/blob/b0b4...0175/src/file.txt#L12-L19.

code-review.customUrl

The custom URL is used to build a full link to the file. The following placeholders are available:

• {sha}: insert the SHA ref for the file
• {file}: insert the file name/path
• {start}: insert the start of the lines selection as an anker
• {end}: insert the end of the lines selection as an anker

{
  "code-review.customUrl": "https://gitlab.com/foo/bar/baz/-/blob/{sha}/src/{file}#L{start}-{end}"
}

This setting would lead into something like this: https://gitlab.com/foo/bar/baz/-/blob/b0b4...0175/src/file.txt#L12-19

code-review.groupBy

This setting is used when generating a report. The comments will be grouped by either:

• filename: default, group by filename
• priority: grouping by priorities
• category: grouping by the used categories

{
  "code-review.groupBy": "category"
}

code-review.categories

Here you can define the categories that will be available for selection when you create comments.

{
  "code-review.categories": [
      "Architecture",
      "Best Practices",
      ...
   ],
}

code-review.reportWithCodeSelection

Define weather to include the code selection(s) in generated reports or not.

{
  "code-review.reportWithCodeSelection": true
}

Attention! The code included in the report will be BASE64 encoded in order to prevent breaking report generation by unescaped characters that will be accidentally interpreted. You can decode this e.g. by using a JS script at the end of the handlebars report template as shown here.

code-review.defaultTemplatePath

The path to a default Handlebars template to be used for HTML default export. The template is used by default when choosing ['Export as HTML with default template'](#export-created notes-as-html) extension command. If not set, the out-of-the-box template provided by this extension is used. The configured value must be the full path to the Handlebars template file.

{
  "code-review.defaultTemplatePath": "/Users/my-user/my-code-review-template.hbs"
}

code-review.priorities

Configure the labels that should be used for the priorities. The first label is used when no priority is defined. The subsequent labels are given in ascending priority (max. 3 priority levels). The defaults are listed below:

{
  "code-review.priorities": [
    "none",   // prio not defined
    "low",    // prio value 1 = green traffic light selected
    "medium", // prio value 2 = yellow traffic light selected
    "high"    // prio value 3 = red traffic light selected
  ] // list must contain exact 4 items
}

Keybindings

To easily add a new comment, you can use the keybinding combination ctrl + ⇧ + n.

The review approach

If you got a customer request for doing a code review you will ideally receive read access to it's github / gitlab repoistory or similar. To create a code review with a report you should install this extension and go on with the following steps:

• Download / clone the customer code and checkout the correct branch
• Open the project in vscode
• Configure th baseURL option with the remote URL
  • this will cause that the link in the report is generate with the correct target including SHA, file and line reference
• Start creating your review notes.
• Export the report.
  • Probably create an own template first
• Send it to the customer or import the notes in your issue tracking system and make the customer happy ♥️

Enjoy!