30.5.1 Comment Commands

The commands in this table insert, kill and align comments:

M-;

Insert or realign comment on current line; alternatively, comment or uncomment the region (comment-dwim).

C-u M-;

Kill comment on current line (comment-kill).

C-x ;

Set comment column (comment-set-column).

C-M-j

M-j

Like <RET> followed by inserting and aligning a comment (comment-indent-new-line). See Multi-Line Comments.

M-x comment-region

C-c C-c (in C-like modes)

Add or remove comment delimiters on all the lines in the region.

The command to create or align a comment is M-; (comment-dwim). The word “dwim” is an acronym for “Do What I Mean”; it indicates that this command can be used for many different jobs relating to comments, depending on the situation where you use it.

When a region is active, M-; either adds or removes comment delimiters on each line of the region. See Mark. If every line in the region is a comment, it removes comment delimiters from each; otherwise, it adds comment delimiters to each. You can also use the commands comment-region and uncomment-region to explicitly comment or uncomment the text in the region (see Multi-Line Comments). If you supply a prefix argument to M-; when a region is active, that specifies how many comment delimiters to add or how many to delete.

If the region is not active, M-; inserts a new comment if there is no comment already on the line. The new comment is normally aligned at a specific column called the comment column; if the text of the line extends past the comment column, M-; aligns the comment start string to a suitable boundary (usually, at least one space is inserted). The comment begins with the string Emacs thinks comments should start with (the value of comment-start; see below). Emacs places point after that string, so you can insert the text of the comment right away. If the major mode has specified a string to terminate comments, M-; inserts that string after point, to keep the syntax valid.

You can also use M-; to align an existing comment. If a line already contains the comment-start string, M-; realigns it to the conventional alignment and moves point after it. (Exception: comments starting in column 0 are not moved.) Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the text inside the comment.

C-u M-; kills any comment on the current line, along with the whitespace before it. To reinsert the comment on another line, move to the end of that line, do C-y, and then do M-; to realign it.

Note that C-u M-; is not a distinct key; it is M-; (comment-dwim) with a prefix argument. That command is programmed so that when it receives a prefix argument it calls comment-kill. However, comment-kill is a valid command in its own right, and you can bind it directly to a key if you wish.

Some major modes have special rules for aligning certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin and are often used for sectioning purposes. Emacs understands these conventions by indenting a double-semicolon comment using <TAB>, and by not changing the indentation of a triple-semicolon comment at all.

     ;; This function is just an example.
     ;;; Here either two or three semicolons are appropriate.
     (defun foo (x)
     ;;;  And now, the first part of the function:
       ;; The following line adds one.
       (1+ x))           ; This line adds one.

For C-like modes, you can configure the exact effect of M-; by setting the variables c-indent-comment-alist and c-indent-comments-syntactically-p. For example, on a line ending in a closing brace, M-; puts the comment one space after the brace rather than at comment-column. For full details see Comment Commands.