Comment boxes for R scripts within Emacs

Without any customization, here is an example of how comment-box can help you:

By default, comment-box inserts a comment box around the desired region; and the box width corresponds to the region width.

Some additional customization may be useful.

First, it would be convenient to define a keybinding for this function : M-x comment-box is quite a long instruction (and you have also to set the region manually, which adds another operation).

ESS handles comments in a particular way, according to the number of # that introduce them. According to the manual:

By default, comments beginning with ‘###’ are aligned to the beginning of the line. Comments beginning with ‘##’ are aligned to the current level of indentation for the block containing the comment. Finally, comments beginning with ‘#’ are aligned to a column on the right

This behavior may be modified, but I find it really useful (and natural since it is consistent with Lisp conventions).

By default, comment-box inserts two # in the left margin of the comment box, so that the box may be indented depending on its position within the R script. But you may want a simple rule such as:

• if the comment box corresponds to a 0-level of indentation, then it should start with three #
• otherwise, the comment box should start with two # only, and will be indented accordingly

This allows to distinguish different levels of information within the R script. Of course, you can provide a prefix argument to the comment-box function to adjust manually the number of # that are required, but this is quite cumbersome. A piece of Lisp code that handles that automatically is given below.

The following Emacs Lisp code might help.

(defun ess-r-comment-box-line ()
  "Insert a comment box around the text of the current line of an R script.
If the current line indentation is 0, the comment box begins with ###.
Otherwise, it begins with ## and is indented accordingly."
  (interactive)
  (save-excursion
    (let ((beg (progn (back-to-indentation)
                      (point)))
          (end (line-end-position)))
      (comment-box beg end
                   (if (> (current-indentation) 0)
                       1
                     2)))))

;; A keybinding specific to ESS-R mode:
(add-hook 'ess-r-mode-hook
          '(lambda ()
             (local-set-key (kbd "\C-cb") #'ess-r-comment-box-line)))

This code allows three things to facilitate and standardize the use of comment boxes into an R script:

1. there is no need to set the region anymore: the comment box is inserted around the text of the current line, automatically
2. the number is # is adjusted according to the level of identation
3. the keybinding C-c b is proposed to trigger the function in ESS-R mode.

Here is an example of its use:

Of course, all this is only an illustration of a possible use and customization of comment-box, and the present example is mainly a matter of personal taste.

Happy comment boxing!