21.6 Manipulating Comments

The comment commands insert, kill and align comments.

M-;

Insert or align comment (indent-for-comment).

C-x ;

Set comment column (set-comment-column).

C-u - C-x ;

Kill comment on current line (kill-comment).

M-LFD

Like RET followed by inserting and aligning a comment (indent-new-comment-line).

The command that creates a comment is Meta-; (indent-for-comment). If there is no comment already on the line, a new comment is created and aligned at a specific column called the comment column. Emacs creates the comment by inserting the string at the value of comment-start; see below. Point is left after that string. If the text of the line extends past the comment column, indentation is done to a suitable boundary (usually, at least one space is inserted). If the major mode has specified a string to terminate comments, that string is inserted after point, to keep the syntax valid.

You can also use Meta-; to align an existing comment. If a line already contains the string that starts comments, M-; just moves point after it and re-indents it to the conventional place. Exception: comments starting in column 0 are not moved.

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.

In C code, a comment preceded on its line by nothing but whitespace is indented like a line of code.

Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the comment.

C-u - C-x ; (kill-comment) kills the comment on the current line, if there is one. The indentation before the start of the comment is killed as well. If there does not appear to be a comment in the line, nothing happens. To reinsert the comment on another line, move to the end of that line, type first C-y, and then M-; to realign the comment. Note that C-u - C-x ; is not a distinct key; it is C-x ; (set-comment-column) with a negative argument. That command is programmed to call kill-comment when called with a negative argument. However, kill-comment is a valid command which you could bind directly to a key if you wanted to.

21.6.1 Multiple Lines of Comments

If you are typing a comment and want to continue it on another line, use the command Meta-LFD (indent-new-comment-line), which terminates the comment you are typing, creates a new blank line afterward, and begins a new comment indented under the old one. If Auto Fill mode is on and you go past the fill column while typing, the comment is continued in just this fashion. If point is not at the end of the line when you type M-LFD, the text on the rest of the line becomes part of the new comment line.

21.6.2 Options Controlling Comments

The comment column is stored in the variable comment-column. You can explicitly set it to a number. Alternatively, the command C-x ; (set-comment-column) sets the comment column to the column point is at. C-u C-x ; sets the comment column to match the last comment before point in the buffer, and then calls Meta-; to align the current line’s comment under the previous one. Note that C-u - C-x ; runs the function kill-comment as described above.

comment-column is a per-buffer variable; altering the variable affects only the current buffer. You can also change the default value. See Locals. Many major modes initialize this variable for the current buffer.

The comment commands recognize comments based on the regular expression that is the value of the variable comment-start-skip. This regexp should not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; for example, in C mode the value of the variable is "/\\*+ *", which matches extra stars and spaces after the ‘/*’ itself. (Note that ‘\\’ is needed in Lisp syntax to include a ‘\’ in the string, which is needed to deny the first star its special meaning in regexp syntax. See Regexps.)

When a comment command makes a new comment, it inserts the value of comment-start to begin it. The value of comment-end is inserted after point and will follow the text you will insert into the comment. In C mode, comment-start has the value "/* " and comment-end has the value " */".

comment-multi-line controls how M-LFD (indent-new-comment-line) behaves when used inside a comment. If comment-multi-line is nil, as it normally is, then M-LFD terminates the comment on the starting line and starts a new comment on the new following line. If comment-multi-line is not nil, then M-LFD sets up the new following line as part of the same comment that was found on the starting line. This is done by not inserting a terminator on the old line and not inserting a starter on the new line. In languages where multi-line comments are legal, the value you choose for this variable is a matter of taste.

The variable comment-indent-hook should contain a function that is called to compute the indentation for a newly inserted comment or for aligning an existing comment. Major modes set this variable differently. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. The function should return the column in which the comment ought to start. For example, in Lisp mode, the indent hook function bases its decision on the number of semicolons that begin an existing comment and on the code in the preceding lines.