Previous: Multi-Line Comments, Up: Comments


31.5.3 Options Controlling Comments

The comment column, the column at which Emacs tries to place comments, is stored in the variable comment-column. You can set it to a number explicitly. Alternatively, the command C-x ; (comment-set-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 does a M-; to align the current line's comment under the previous one.

The variable comment-column is per-buffer: setting the variable in the normal fashion affects only the current buffer, but there is a default value which you can change with setq-default. 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. Make sure this regexp does 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, and accepts C++ style comments also. (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 Regexp Backslash.)

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, so that it will follow the text that you will insert into the comment. When comment-end is non-empty, it should start with a space. For example, in C mode, comment-start has the value "/* " and comment-end has the value " */".

The variable comment-padding specifies how many spaces comment-region should insert on each line between the comment delimiter and the line's original text. The default is 1, to insert one space. nil means 0. Alternatively, comment-padding can hold the actual string to insert.

The variable comment-multi-line controls how C-M-j (indent-new-comment-line) behaves when used inside a comment. Specifically, when comment-multi-line is nil, the command inserts a comment terminator, begins a new line, and finally inserts a comment starter. Otherwise it does not insert the terminator and starter, so it effectively continues the current comment across multiple lines. In languages that allow multi-line comments, the choice of value for this variable is a matter of taste. The default for this variable depends on the major mode.

The variable comment-indent-function should contain a function that will be called to compute the indentation for a newly inserted comment or for aligning an existing comment. It is set differently by various major modes. 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. It should return the column in which the comment ought to start. For example, in Lisp mode, the indent hook function bases its decision on how many semicolons begin an existing comment, and on the code in the preceding lines.