31.5.1 Comment Commands
The comment commands in this table insert, kill and align comments.
They are described in this section and following sections.
- Insert or realign comment on current line; alternatively, comment or
uncomment the region (
- C-u M-;
- Kill comment on current line (
- C-x ;
- Set comment column (
- 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.
If there is no comment already on the line, M-; inserts a new
comment, aligned at a specific column called the comment column.
The new comment begins with the string Emacs thinks comments should
start with (the value of
comment-start; see below). Point is
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 too, to keep the syntax valid.
If the text of the line extends past the comment column, then the
comment start string is indented to a suitable boundary (usually, at
least one space is inserted).
You can also use M-; to align an existing comment. If a line
already contains the comment-start string, M-; reindents 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
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 is a valid command
in its own right, and you can bind it directly to a key if you wish.
M-; does two other jobs when used with an active region in
Transient Mark mode (see Transient Mark). Then it either adds or
removes comment delimiters on each line of the region. (If every line
is a comment, it removes comment delimiters from each; otherwise, it
adds comment delimiters to each.) If you are not using Transient Mark
mode, then you should use the commands
uncomment-region to do these jobs (see Multi-Line Comments).
A prefix argument used in these circumstances specifies how many
comment delimiters to add or how many to delete.
Some major modes have special rules for indenting 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. 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 buffers, you can configure the exact effect of M-;
more flexibly than for most buffers by setting the user options
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