Recently, I found myself needing a solution for tracking issues and comments in source code during a review. Org mode makes this task much better and easier overall.
First, let me explain how it is better. During a review, most comments
focus on issues on particular line numbers. This means that the code
needs must have line numbers displayed. That way, everyone can be
clear about the particular line for a given issue. In emacs, this is
easily done with
linum-mode. This completes the first
requirements of being able to view the code.
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.
Adding a reviewer name to an item (as a property) will make it easy for the code author to go back and clarify after a meeting. Tracking ownership also lets the author know who should review the fix if necessary.
The sorting features in org-mode also provides the ability to sort on properties, so lumping together reviewers' comments should not be difficult.
If you use and capture times, even more sorting can reflect the order of items raised in the meeting. This would help as you read through the code again to see the issues in that order.
Assigned deadlines also provide sorting methods. Items arranged by due date could be another view of the task list.
Certain features or bugs may align with a milestone. If this is something to consider, then the capture templates could provide tagging functionality. Later, the tags give a way to track sets of tasks together and get a picture of the progress.