ヒントと標準的な作法

この章にはEmacs Lispの新たな機能の説明ではなく、前章までに説明された 機能を効果的に使用するためのアドバイスが記述されています。

明確なLispプログラムの記述

以下は、広く使用されることを目的とするLispコードを書くときによく犯され る誤りを避けるためのヒントや作法です。

• 全ての大域変数は同じ名前空間を共有し、全ての関数も大域変数とは別の名前 空間を共有します。そこで、他のLispプログラムのものと区別する短い単語を 選び、全ての大域変数、定数、関数の名前がこの単語で始まるようにしてく ださい。これにより名前の衝突が起きることを防ぐことができます。 この規則は、Emacs Lispではプリミティブではないが、伝統的なLispでは primitiveであるものの名前にも(たとえばcadrであっても)適用されます。 たとえば、いくつものcadrを定義するうまい方法があります。安全のた めに、cadrとせずに、foo-cadrもしくはmylib-cadrなど としてください。 ある名前(たとえばtwiddle-filesという名前で)でEmacsの配布に加えら れるべきだと思われる関数を書いたときも、あなたのプログラムの中でその名前 を使って呼ばないでください。とりあえず、あなたのプログラムの中では mylib-twiddle-filesと呼んでおいて、その関数をEmacsに加えるよう `bug-gnu-emacs@prep.ai.mit.edu'宛にメイルを送ってください。 一つの接頭語では不十分である場合は、意味があるのであれば複数の共通な接 頭語を使っても構いません。 接頭語と残りのシンボル名はハイフン`-'で区切ってください。これは Emacs自身やほとんどのEmacs Lispプログラムと一貫します。
• 少なくともライブラリ・プログラムが複数のエントリ・ポイントをもつのであれ ば、そのライブラリ・プログラムの中でprovide関数を用いると便利 です。
• あるファイルが他のライブラリ・プログラムをあらかじめロードしておくことが 必要であれば、ファイルの先頭のコメントに明記してください。またそれらの ライブラリ・プログラムを確実にロードするように、requireを使用して ください。
• ファイルfooが、別のファイルbarで定義されたマクロを使用する場 合は、foo内でそのマクロを最初に使用する以前に、requireが必 要です。

  (eval-when-compile (require 'bar))
  

  なお、requireがうまく働くためには、barが(provide ' bar)を含んでいなければなりません。 このようにすることにより、fooがバイト・コンパイルされるときに barがロードされます。こうしないと、必要なマクロをロードせずに fooをコンパイルしてしまうため、コンパイルされたコードは正しく動 作しなくなります。See section マクロとバイトコンパイル。 eval-when-compileを用いることにより、コンパイルされたfooが 使用されるときに、barがロードされるのを防ぐことができます。
• 新たな主モードを定義するときは、通常の主モードが行っているように、 run-hooksを用いてフック変数を実行するようにしてください。 See section フック。
• ある関数の目的が、ある条件が真であるか偽であるかを調べるものである場合は、 その関数名を`p'で終るようにしてください。名前が一語であるときは、単 に`p'をつけてください。名前が複数の単語からなる場合は、`-p'を つけてください。(例framep、frame-live-p)
• ユーザ・オプション変数が真偽の条件を記録するものであるときは、 `-flag'で終る名前にしてください。
• 主モードでC-c letterをキーとして定義しないでください。これら のシーケンスはユーザのために残してあるものです。ユーザのために予約されて いるのは、これらのシーケンスだけですから、これらを使用されると 困ります。 かわりにC-c non-letterというシーケンスを用いてください。 これは主モードのために予約されています。 この規約に従うように、Emacsバージョン18の全ての主モードを変更するのは大 変な作業でした。この規約を守らないことは、その作業を無駄にし、さらにはユー ザにとっても不便です。
• C-cに{、}、<、>、:もしくは ;が続くシーケンスも主モードのために予約されています。
• C-cに他の句読点文字が続くシーケンスは、副モードに割り当てられてい ます。それらを主モードで使用することが完全に禁止されているわけではありま せんが、もし主モードで使用すると、主モードでのキー・バインドが副モードに より変更されるということが起きます。
• 他の(C-cも含めた)前置文字にC-hが続くシーケンスをバインドしな いようにしてください。C-hをバインドしなければ、C-hは自動的に、 その前置文字のサブコマンドのリストを表示するヘルプ文字となります。
• 連続した二つのESCで終る場合を除いて、ESCで終るキー・シー ケンスをバインドしてはなりません(つまりESC ESCで 終るシーケンスを用いることは構いません)。 ある状況(context)で前置文字以外でESCをバインドすると、その状況での ファンクション・キーによるエスケープ・シーケンスと区別がつかなくなるため、 この規則があります。
• アプリケーションは、シフト・キーを押した状態のマウス・ボタン1によるイベ ントをバインドしてはいけません。つまりS-mouse-1、M-S-mouse-1、 C-S-mouse-1などが禁止されます。これらはユーザのために予約されてい ます。
• ユーザが通常バッファのテキストを変更しないようなモードであれば、そのバッ ファのテキストからの参照を行うようなコマンドにmouse-2を用いてくだ さい。Dired、Info、Compilation、Occurなどのモードがこの例です。
• あるパッケージが通常のEmacsの振舞いを変更するようなものである場合は、そ の効果を有効および無効にするコマンドを提供するのがよいでしょう。その効果 を有効もしくは無効にするためにwhatever-modeという名前のコマ ンドを定義し、それを自動ロード(autoload)してください(see section 自動ロード)。 パッケージを単にロードしただけでは目に見える効果がないよう、つまりその効 果を有効にしないように設計してください。そうしてユーザがそのコマンドを起 動することによって効果を有効にします。
• Emacsのプリミティブに別名(alias)を定義しないでください。標準の名前を 用いてください。
• Emacsのプリミティブを再定義するのは特に避けてください。それは特定のプ ログラムに対してはうまく動作するかもしれませんが、ほかのプログラムに対 しても動作する保証はどこにもありません。
• あるファイルが標準的なEmacsの関数やライブラリ・プログラムを置き換 えるのであれば、そのファイルの先頭にどの関数が置き換えられ、もとの関数 とどのように振舞いが変わるかを目立つように記述してください。
• Emacs Lispソース・ファイルの名前は13文字以下にしてください。こうすること によって、そのファイルをコンパイルしても、そのコンパイルされたファイルの 名前は14文字以下になります。これは全てのUnixシステムに十分な長さです。
• プログラムの中でnext-lineとprevious-lineを使用しないで ください。ほとんど全ての場合forward-lineの方が便利であり、安 全です。See section テキスト行単位での移動。
• マークを設定することがあなたのプログラムの意図した目的でないかぎり、マー クを設定する関数を呼んではなりません。マークはユーザが用いるものであるた め、ユーザのためになるのではないかぎりマークを変えてはなりません。 See section マーク。 特に以下の関数は用いてはいけません。
  • beginning-of-buffer, end-of-buffer
  • replace-string, replace-regexp
  これらの関数のマークを変更するという機能をユーザに対して提供するつもりで はなく、ただ単にポイントを移動したい、もしくは文字列を置き変えたいという のであれば、これらの関数を1、2行の簡単なLispコードで置き換えることができ ます。
• ベクタを使う特別な理由がないかぎり、ベクタのかわりにリストを使用し てください。Lispはベクタよりもリストを扱う機能を多く持っているため、 通常リストを用いる方が便利です。 ベクタは、要素の挿入や削除が必要でなく(リストだけがこのようなことができ ます)、(最初から最後まで検索するのではなく)不規則にアクセスするような大 きなテーブルには有効です。
• エコー領域にメッセージを表示するためには、princよりもmessage 関数の方が適切です。See section エコー領域。
• エラー状態を検出した場合は、関数error (もしくはsignal) を呼んでください。関数errorはもとの関数に返りません。 See section エラーを発行する方法。 エラーの通知にmessage、throw、sleep-forもしくは beepを使用しないでください。
• エラー・メッセージは大文字で開始してください。またピリオドでは終らない でください。
• 再帰編集(recursive edit)を使うことは避けてください。そのかわりに、Rmail のeコマンドが行っているように、もとのローカル・キーマップに戻るよ うなコマンドを含む、新たなキーマップを用いてください。もしくは edit-optionsコマンドが行っているように、別のバッファに切り替わっ た後、ユーザの操作により元に戻るようにしてください。See section 再帰編集。
• 他のいくつかのシステムでは、変数の名前の最初と最後を`*'とする規約が あります。Emacs Lispではこの規約を採用しません。あなたのプログラムでも採 用しないでください(Emacsではこのような名前をプログラムによって生成される バッファの名前にのみ用います)。全てのライブラリが同じ規約を用いていれば、 ユーザにEmacsがより一貫性があるように見えます。
• それぞれの関数を、デフォルトの字下げパラメータを用いたC-M-q (indent-sexp)によって字下げしてください。
• 閉じ括弧を一行に一つずつ記述するような習慣をつけないでください。Lispプロ グラマの間では、これはよくない書き方であるとされています。ただしまれに、 多くの閉じ括弧が連続するようなときに、それらを一つか二つに分けて記述する のが有効であるような場合もあります。
• 複製したものを誰かに渡すときは、著作権表示をつけてください。Emacsの配布 中のLispファイルの先頭にあるものと同じものを用いてください。あなたがFSF に著作権を譲渡する書式に署名をしたことがないのであれば、著作権表示のFSF の名前があるところにあなたの名前を入れてください。

コンパイルされたコードを速くする

バイト・コンパイルされたLispプログラムの実行速度を改善する方法につい て説明します。

• プログラムのプロファイルを取るために、`profile'ライブラリを使用して ください。詳細は`profile.el'を参照してください。
• 可能なかぎり、再帰呼出しを使わず、繰り返しを使ってください。Emacs Lispで は、コンパイルされた関数が別のコンパイルされた関数から呼ばれる場合でも、 関数呼出しは遅いものです。
• プリミティブのリスト検索関数のmemq、member、assqも しくはassocを使う方が、明示的な繰り返しを使うよりずっと高速です。 これらのプリミティブ検索関数が使えるように、データ構造自体を再検討するの もよいでしょう。
• いくつかの組込み関数は、バイト・コンパイルされたコードでは通常の関数 呼出しが行なわれないように特別に扱われます。これらの関数を使うことを推 奨します。ある関数をコンパイラがこのように特別扱いするかどうかを調べるに は、その関数のbyte-compile属性を調べてください。もし byte-compile属性がnilでなければ、その関数は特別扱いさ れます。 たとえば次のようにすれば、arefは特別扱いされるが(see section 配列に関する関数)、eltは特別扱いされないされないことがわかります (see section シーケンス)。

  (get 'aref 'byte-compile)
       => byte-compile-two-args
  
  (get 'elt 'byte-compile)
       => nil
  

• あなたのプログラムの実行時間の多くを小さな関数の実行が占めるのであれば、 それをインライン関数にしてください。これにより関数呼出しを省くことができ ます。ただし関数をインラインにするとプログラムの変更時に制約が生ずるため、 ユーザにとって速度が気になるぐらい遅いところを高速化する目的以外には使用 しないでください。See section インライン関数。

読みやすい説明文字列を書く

説明文字列(documentation string)の書き方の作法について説明します。

• ユーザが知る必要のある全てのコマンド、関数、変数に説明文字列をつけてく ださい。
• Lispプログラムの内部的な関数やサブルーチンでも、説明文字列があるとよ い場合があります。初期のEmacsでは説明文字列のかわりにコメントを使う方 がメモリ効率の点で有利でしたが、現在のバージョンではそのようなことはあ りません。
• 説明文字列の最初の一行は、要約を表わす一つか二つの完全な文にしてください。 M-x aproposはこの一行だけを表示するので、要約が示されなければ使い ものになりません。さらに行を大文字で開始し、ピリオドで終ってください。 説明文字列にその関数や変数の使用法の詳細を加えることもできます。これらの 行も完全な文としてください。ただし、これらはそれが見やすいのであれば、行 詰め(fill)を行ってください。
• 一貫性のために、説明文字列の最初の行の動詞を "to" を除いた不定詞とし て表わしてください。たとえば、"Returns the cons of A and B." とする よりも "Return the cons of A and B." としてください。通常は最初のパラ グラフの残りの部分もこうするとよいでしょう。逆に残りのパラグラフは主語 がある方がよいでしょう。
• 説明文字列は、受動態ではなく能動態で、未来形ではなく現在形で書いてくだ さい。たとえば "A list containing A and B will be returned." とせずに "Return a list containing A and B." としてください。
• 不必要に "cause" という単語(もしくはその同義語)を使わないでください。 たとえば "Cause Emacs to display text in boldface," ではなく "Display text in boldface." としてください。
• 説明文字列を空白文字で開始したり、終ったりしないでください。
• 80桁の画面のEmacsウィンドウに合うように、説明文字列を構成してください。 ほとんどの行を60文字を越さないようにするとよいでしょう。ただし最初の行だ けは、そこに入れるべき情報を記述するために、さらに長くしても構いません。 単に説明文字列全体を行詰めをするのではなく、注意して改行を入れるとずっと 読みやすくなります。説明文字列が長い場合は、話題ごとに空白行で区切ってく ださい。
• ソース・コード中で最初の行に揃うように説明文字列の2行目以降を字下げして はいけません。ソース・コードでの見ためはよくなりますが、ユー ザには読みにくくなります。最初の二重引用符(double-quote)の前の字下げ は、文字列の一部ではないことに気をつけてください。
• ユーザが対話的に設定するような変数の場合は、変数の説明文字列の最初の文 字を`*'としてください。その値が長いリストや関数であったり、初期 化ファイルの中でのみ設定するようなものの場合は、説明文字列を`*' で開始しないでください。See section グローバル変数の定義。
• 真か偽かを示す変数の説明文字列の最初は、"nilでない場合は ..." などというようにしてください。こうすることによって、全ての nilでない値が等価であることを明確になり、nilおよび nilでない値がそれぞれ何を意味するのかも明確に示されます。
• 関数の説明文字列がその引数の値について説明する場合は、引数の名前を大文 字にしてそれがその値の名前であるように表記してください。たとえば関数 /の説明文字列では、2番目の実引数の名前がdivisorで あるため、それを`DIVISOR'としています。 たとえばリストやベクタを、変化する文法的要素(subunits)に分解して代表的に 示す場合などは、メタ構文上の変数(meta-syntactic variable)は全て大文字と してください。(29)
• 説明文字列がLispシンボルを参照するときは、引用符(single-quoate) で囲い、それが表示されるように(通常は小文字で)記述してください。(例: ``lambda'')ただし例外が二つあり、tとnilは引用符 をつけないで記述してください。
• 説明文字列に直接キー・シーケンスを書かないでください。そのかわりに `\\[...]'形式を用いてください。たとえば、`C-f'と書く代わり に`\\[forward-char]'と書いてください。Emacsが、説明文字列を表示する ときに、forward-charが対応づけられているキーに置き換えます(この例 では、通常は`C-f'となりますが、ユーザがキー・バインドを変更している 場合は別の文字となります)。See section 説明文字列でのキー・バインドの置換。
• 主モードの説明文字列では、グローバル・マップではなく、そのモードのローカ ル・マップのキー・バインドを参照するのが望ましいでしょう。したがって、ど のキー・マップが用いられるか示すために、説明文字列中で一度 `\\<...>'形式を使用してください。さらにこれは最初に使われる `\\[...]'よりも以前に行ってください。`\\<...>'の中は、 その主モードのローカル・キーマップを格納する変数の名前としてください。 説明文字列の表示が遅くなるため、`\\[...]'を何度も何度も使うの は実用的ではありません。主モードの最も重要なコマンドの説明にのみ使用し て、そのモードのキーマップのその他のものの表示には`\\{...}' を使用してください。

コメントの書き方

ここに書かれているようにコメントを記述し、字下げを行うことが推奨されま す。

`;'

一つのセミコロン(`;')で始まるコメントは、全てソース・コードの右側の 同じ桁に揃えてください。通常これらのコメントは、同じ行のコードが何をする かを説明するのに用いられます。Lispモードや関連するモードでは、M-; (indent-for-comment)コマンドが、自動的に正しい場所にこの`;' を挿入したり、すでにコメントがある場合はその位置を揃えたりします。 この例およびこれ以降の例はEmacsのソースのものです。

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

`;;'

二つのセミコロン(`;;')で始まるコメントは、コードの字下げと同じ位置 に揃えてください。通常これらのコメントは、それ以降の行の目的や、その位置 でのプログラムの状態を記述します。たとえば、

(prog1 (setq auto-fill-function
             ...
             ...
  ;; update mode line
  (force-mode-line-update)))

(そのパッケージ内でのみ使用されるため)説明文字列を持たない関数には、かわ りにその関数が何を行ないどのように呼ばれるのが正しいかを説明する二つのセ ミコロンから始まるコメントを書くべきです。それぞれの引数の意味とその値を 関数がどのように用いるかを正確に説明してください。

`;;;'

三つのセミコロン(`;;;')で始まるコメントは、左マージンの位置から開始 してください。このようなコメントは、関数定義の外でのそのプログラムの設計 方針を説明する一般的な記述に用いられます。

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

三つのセミコロンで始まるコメントのもう一つの使い方は、関数の中の行をコ メント・アウトするものです。コメントが左マージンに残るようにこの目的に 使用します。

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

`;;;;'

四つのセミコロン(`;;;;')で始まるコメントは、左マージンの位置から開 始し、プログラムの大きな区切りごとの先頭に用いられます。たとえば

;;;; The kill ring

M-; (indent-for-comment)やTAB (lisp-indent-line)などのEmacsのLispモードの字下げ命令は、自動的に この規約に従って字下げを行ないます。See section `Manipulating Comments' in The GNU Emacs Manual。

Emacsライブラリのヘッダの規約

Emacsバージョン19では、Lispライブラリを段落に分けたり、その作者 などの情報を付加するために特別なコメントの規約を定めています。この節で はこれらの規約について説明します。まず最初に例を示します。

;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers

;; Copyright (C) 1992 Free Software Foundation, Inc.

;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
;; Created: 14 Jul 1992
;; Version: 1.2
;; Keywords: docs

;; This file is part of GNU Emacs.
copying permissions...

1番先頭の行は次の書式です。

;;; file名 --- 説明

説明(description)は一行に納めてください。

著作権表示に続いて、数行のヘッダ・コメント(header comment)行 が置かれます。それぞれ`;; header名:'で始まります。以下が header名で使われる規約の表です。

`Author'

この行には、ライブラリの少なくとも最初の作者の名前とネットワーク・アドレ スを記述します。 複数の作者がいる場合は、次のように;;とタブ文字で始まる継続 行を用いて記述します。

;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
;;      Dave Sill <de5@ornl.gov>
;;      Dave Brennan <brennan@hal.com>
;;      Eric Raymond <esr@snark.thyrsus.com>

`Maintainer'

この行には、Author行のように、一人分の名前とアドレスもしくは一人分のアド レスのみ、もしくは`FSF'と書きます。この行が省略された場合は、Author 行の作者が管理を行っているものとみなされます。上の例は、maintainer行が冗 長であるため、あまりよい例ではありません。 手で名前を埋め込まなくとも "管理者へmailを送る" Lisp関数を作ること を可能とすることが、`Author'行と`Maintainer'行のもう一つの目 的です。 ネットワーク・アドレスとフル・ネームを両方記述する場合は、必ずネッ トワーク・アドレスを`<...>'で囲ってください。

`Created'

この行には、最初にファイルを作成した日付を記述します。省略可能です。歴史 的な興味のためだけのためにあります。

`Version'

個々のLispプログラムにバージョン番号を記録したいのであれば、この行に 記述してください。

`Adapted-By'

この行には、(たとえばこの規約に従うように変更をした場合のように)ライブラ リのあまり内部にかかわらないような(30)変更を行った人の名前を記述してください。

`Keywords'

この行には、finder-by-keywordヘルプ命令のためのキーワードを記述し ます。ユーザは、やりたいことから探すときに、あなたのプログラムをこのキー ワードから探すため、この行は重要です。キーワードを分けるときは、空白文字、 コンマ、もしくはその両方を用います。

少なくとも`Author'と`Keywords'の行は、全てのLispライブラリに 必要です。適切であれば他の行も使用してください。別のヘッダ名の行を加えて も構いません。標準的な意味はないため何の害もありません。

我々は、ライブラリ・ファイルの内容をいくつかに分割するために標準的なコ メントを決めています。以下がその表です。

`;;; Commentary:'

そのライブラリがどのように働くかを説明する紹介説明の始まりを示します。 著作権許可のすぐ後にあるべきです。

`;;; Change log:'

(変更履歴を記述する場合の)ライブラリ・ファイルの変更履歴の始まりを示しま す。Emacsとともに配布されるほとんどLispファイルでは、変更履歴は `ChangeLog'に書かれており、ソース・ファイル中には全く記述されていま せん。したがってこれらのファイルには`;;; Change log:'行はありません。

`;;; Code:'

実際のプログラム・コードの始まりを示します。

`;;; filename ends here'

これはフッタ行(footer line)で、ファイルの1番最後の行です。このフッ タ行がないことから、ファイルの後部が切り取られたバージョンであることを知 ることができます。

Go to the first, previous, next, last section, table of contents.