comparison lispref/tips.texi @ 53924:ed40e77a5176

(Comment Tips): Document the new conventions for commenting out code.

53923:3517efa33c1f

@item ;;;
Comments that start with three semicolons, @samp{;;;}, should start at
the left margin.  These are used, occasionally, for comments within
functions that should start at the margin.  We also use them sometimes
for comments that are between functions---whether to use two or three
semicolons there is a matter of style.

Another use for triple-semicolon comments is for commenting out lines
within a function.  We use three semicolons for this precisely so that
they remain at the left margin.

@smallexample
(defun foo (a)
;;; This is no longer necessary.
;;;  (force-mode-line-update)
  (message "Finished with %s" a))
@end smallexample

@item ;;;;
Comments that start with four semicolons, @samp{;;;;}, should be aligned
to the left margin and are used for headings of major sections of a
program.  For example:

53924:ed40e77a5176

@item ;;;
Comments that start with three semicolons, @samp{;;;}, should start at
the left margin.  These are used, occasionally, for comments within
functions that should start at the margin.  We also use them sometimes
for comments that are between functions---whether to use two or three
semicolons depends on whether the comment should be considered a
``heading'' by Outline minor mode.  By default, comments starting with
at least three semicolons (followed by a single space and a
non-whitespace character) are considered headings, comments starting
with two or less are not.

Another use for triple-semicolon comments is for commenting out lines
within a function.  We use three semicolons for this precisely so that
they remain at the left margin.  By default, Outline minor mode does
not consider a comment to be a heading (even if it starts with at
least three semicolons) if the semicolons are followed by at least two
spaces.  Thus, if you add an introductory comment to the commented out
code, make sure to indent it by at least two spaces after the three
semicolons.

@smallexample
(defun foo (a)
;;;  This is no longer necessary.
;;;  (force-mode-line-update)
  (message "Finished with %s" a))
@end smallexample

When commenting out entire functions, use two semicolons.

@item ;;;;
Comments that start with four semicolons, @samp{;;;;}, should be aligned
to the left margin and are used for headings of major sections of a
program.  For example: