Org Mode for Code Reviews

Now a note-taker in the meeting faces the issue of tracking all of the comments and issues given by the reviewers. This can be a tedious task. First, get the line with the issue, capture the issue and assign a priority. All of this goes into a list for the author to consider when fixing the codebase.

Org-mode makes this task much easier with its ability to capture issues quickly and with context. With a keystroke, a scribe can more easily fill in the details given and assign a priority. The following code sets up some templates to use for the review. The bugs have a priority and fall under the "Issues" heading while the questions get put under the "Questions" heading.

(org-remember-insinuate)
(define-key global-map "\C-cr" 'org-remember)
(setq org-remember-templates
      '(("Code Review High" ?h "* TODO [#A] %?\n  %i\n  %a" "~/Review.org" "Issues")
        ("Code Review Medium" ?m "* TODO [#B] %?\n  %i\n  %a" "~/Review.org" "Issues")
        ("Code Review Low" ?l "* TODO [#C] %?\n  %i\n  %a" "~/Review.org" "Issues")
        ("Code Review Question" ?? "* TODO %?\n  %i\n  %a" "~/Review.org" "Questions")))

Note that I used org-remember (instead of org-capture) because my coworkers are on emacs 23.2 so I had to be compatible wit the default version of org-mode for that emacs version.

There is one additional sticking point to discuss for this solution. The links produced are really a search string within the file. That means that if there are two lines with the same content, the link would find only the first occurrence of the line. The main concern is that a comment on a later line could link (accidentally) to an earlier line. There are two ways to look at this. First, you may feel that the issue is the same regardless of the line (if they are the same lines), so linking to one over the other is a minor detail. Or, you may feel that the exact line is the important item to capture and, in that case, you would need a line number.

There is a way to link using only line numbers. Use the code shown below to create the file search string from the line number.

(defun my/linenum()
  "Use line number as the file linking item"
;; Optionally, predicate this technique to
;; only certain modes
;; e.g.
;; (when (eq major-mode 'cperl-mode) ...
  (number-to-string (org-current-line)))
(add-hook 'org-create-file-search-functions
          'my/linenum)

As indicated by the comments, this linking stragety can also predicate on the major mode used for finer control.

Once setup is complete, simply follow along in the source code. When an issue or question comes up, hit C-c r and select the proper template. Fill in the details and complete the entry. You will be back in the source code buffer ready to consider the next issue.

After the review, you can easily sort the issues by priority. Go to the header for the issues and hit C-c ^. A prompt will ask you how to sort. In this case, select priority and the list sorts correctly.

The TODO items make it easy for the author to track the progress against the review tasks.

The templates themselves could provide more information about the given issues in the review.