[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A. Tips and Standards

This chapter describes no additional features of XEmacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.1 Writing Clean Lisp Programs

Here are some tips for avoiding common errors in writing Lisp code intended for widespread use:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.2 Tips for Making Compiled Code Fast

Here are ways of improving the execution speed of byte-compiled Lisp programs.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.3 Tips for Documentation Strings

Here are some tips for the writing of documentation strings.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.4 Tips on Writing Comments

We recommend these conventions for where to put comments and how to indent them:

;

Comments that start with a single semicolon, ‘;’, should all be aligned to the same column on the right of the source code. Such comments usually explain how the code on the same line does its job. In Lisp mode and related modes, the M-; (indent-for-comment) command automatically inserts such a ‘;’ in the right place, or aligns such a comment if it is already present.

This and following examples are taken from the Emacs sources.

 
(setq base-version-list                 ; there was a base
      (assoc (subseq fn 0 start-vn)     ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion
;;

Comments that start with two semicolons, ‘;;’, should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. For example:

 
(prog1 (setq auto-fill-function
             …
             …
  ;; update modeline
  (redraw-modeline)))

Every function that has no documentation string (because it is used only internally within the package it belongs to), should have instead a two-semicolon comment right before the function, explaining what the function does and how to call it properly. Explain precisely what each argument means and how the function interprets its possible values.

;;;

Comments that start with three semicolons, ‘;;;’, should start at the left margin. Such comments are used outside function definitions to make general statements explaining the design principles of the program. For example:

 
;;; This Lisp code is run in XEmacs
;;; when it is to operate as a server
;;; for other processes.

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

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

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

 
;;;; The kill ring

The indentation commands of the Lisp modes in XEmacs, such as M-; (indent-for-comment) and <TAB> (lisp-indent-line) automatically indent comments according to these conventions, depending on the number of semicolons. See (xemacs)Comments section ‘Manipulating Comments’ in The XEmacs User’s Manual.



[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.