Frédéric Santos' notebook
Emacs and R tricks for anthropologists and archaeologists.
06 avril 2020

# Comment boxes for R scripts within Emacs

Some people like to insert nice comment boxes in their R scripts. Using Emacs and ESS, this is easy to achieve thanks to the lisp function comment-box.

## A first example

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.

## A possible keybinding

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).

## Automatically adjust the number of # in the left margin of the comment box

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.

## A proposition of Lisp code

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:
'(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!