[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [表紙] [目次] [索引] [検索] [上端 / 下端]

B. ヒントと慣習

URL="https://bookshelf.jp/cgi-bin/goto.cgi?file=elisp21&node=Tips"
"texi/elisp21/B.ヒントと慣習"へのコメント(無し)

本章では、Emacs Lispの機能についてさらに述べることはしません。 かわりに、前章までに述べてきた機能を効率よく使うための助言や Emacs Lispプログラマが従うべき慣習について述べます。



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [表紙] [目次] [索引] [検索] [上端 / 下端]

B.1 Emacs Lispのコーディングの慣習

URL="https://bookshelf.jp/cgi-bin/goto.cgi?file=elisp21&node=Coding%20Conventions"
"texi/elisp21/B.1EmacsLispのコーディングの慣習"へのコメント(無し)

ここでは、読者が広く使われることを意図した Emacs Lispコードを書く場合に従うべき慣習について述べます。



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [表紙] [目次] [索引] [検索] [上端 / 下端]

B.2 コンパイル済みコードを速くするヒント

URL="https://bookshelf.jp/cgi-bin/goto.cgi?file=elisp21&node=Compilation%20Tips"
"texi/elisp21/B.2コンパイル済みコードを速くするヒント"へのコメント(無し)

バイトコンパイルしたLispプログラムの実行速度を改良する方法を示します。



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [表紙] [目次] [索引] [検索] [上端 / 下端]

B.3 説明文字列に関するヒント

URL="https://bookshelf.jp/cgi-bin/goto.cgi?file=elisp21&node=Documentation%20Tips"
"texi/elisp21/B.3説明文字列に関するヒント"へのコメント(無し)

説明文字列を書くうえでのヒントや慣習を述べます。 コマンドM-x checkdoc-minor-modeを実行して、 これらの慣習の多くを確認できます。



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [表紙] [目次] [索引] [検索] [上端 / 下端]

B.4 コメントの書き方のヒント

URL="https://bookshelf.jp/cgi-bin/goto.cgi?file=elisp21&node=Comment%20Tips"
"texi/elisp21/B.4コメントの書き方のヒント"へのコメント(無し)

コメントを置く場所とそれらの字下げ方法については以下のような慣習を推奨します。

`;'
1つのセミコロン`;'で始まるコメントは、 ソースコードの右側で同じコラム位置に揃えること。 そのようなコメントは、その行のコードの動作を説明する。 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

`;;'
2つのセミコロン`;;'で始まるコメントは、 その部分のコードの字下げに揃えること。 そのようなコメントは、その後続の行の目的や その箇所でのプログラムの状態を記述する。

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

説明文字列を持たない各関数 (所属するパッケージで内部向けにのみ使用される関数)では、 関数が行うことと正しい呼び出し方を記述した 2つのセミコロンで始まるコメントを関数のまえに書くこと。 各引数の意味とその可能な値を関数がどのように解釈するかを正確に説明すること。

`;;;'
3つのセミコロン`;;;'で始まるコメントは、左端に揃えること。 そのようなコメントは、関数定義の外側で使い、 プログラムの設計原理を説明する一般的な表明である。 たとえばつぎのとおり。

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

3つのセミコロンで始まるコメントの別の使い方は、 関数内の行をコメントにする場合である。 そのような行が左端に留まるように3つのセミコロンを使うのである。

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

`;;;;'
4つのセミコロン`;;;;'で始まるコメントは、 左端に揃えて、プログラムの主要な部分のヘッダに使う。 たとえばつぎのとおり。

 
;;;; The kill ring

M-;indent-for-comment)や TABlisp-indent-line)などの Emacsのlispモードの字下げコマンドは、 これらの慣習にしたがって自動的にコメントを字下げします。 See GNU Emacs マニュアル。



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [表紙] [目次] [索引] [検索] [上端 / 下端]

B.5 Emacsライブラリのヘッダの慣習

URL="https://bookshelf.jp/cgi-bin/goto.cgi?file=elisp21&node=Library%20Headers"
"texi/elisp21/B.5Emacsライブラリのヘッダの慣習"へのコメント(無し)

Emacsには、コメントをいくつかの部分に分けて作者などの情報を与えるために、 Lispライブラリの特別なコメントに対する慣習があります。 本節ではそれらの慣習について述べます。 まず、例を示します。

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

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

;; Author: Eric S. Raymond 
;; Maintainer: Eric S. Raymond 
;; Created: 14 Jul 1992
;; Version: 1.2
;; Keywords: docs

;; This file is part of GNU Emacs.
...
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

最初の行はつぎの形式であるべきです。

 
;;; filename --- description

この記述は1行で完全になるようにします。

著作権表示のあとには、`;; header-name:'で始まる いくつかのヘッダコメント(header comment)行が続きます。 header-nameに使う可能性のある慣習の一覧を以下に示します。

`Author'
この行では、少なくともライブラリの主作者の 氏名とネットワークアドレスを明記する。

複数の作者がいる場合には、以下のように、 ;;とタブ文字で始めた継続行に その人達を列挙する。

 
;; Author: Ashwin Ram 
;;      Dave Sill 
;;      Dave Brennan 
;;      Eric Raymond 

`Maintainer'
この行には、作者行(`Author')のように1人の氏名とアドレス、 アドレスのみ、文字列`FSF'のいずれかを書く。 保守者行(`Maintainer')がない場合には、 作者行の人達が保守していると仮定する。 上の例は、保守者行が冗長であり、少々いんちきである。

作者行(`Author')と保守者行(`Maintainer')の考えは、 手作業で名前を探さずに『保守者にメイルを送る』ようなLisp関数を 作れるようにするためである。

ネットワークアドレスに加えて人の氏名も書く場合には、 ネットワークアドレスを`<...>'で必ず囲むこと。

`Created'
この行は省略できるが、ファイルの作成日時を書く。 歴史的な意味だけである。

`Version'
各Lispプログラムの版番号を記録しておきたい場合に、 この行に版番号を書く。

`Adapted-By'
このヘッダ行では、(たとえば、スタイルの慣習に適合するように変更したなどの) インストールのためにライブラリを受理した人の名前を書く。

`Keywords'
この行には、ヘルプコマンドfinder-by-keyword向けの キーワードを書く。 意味のあるキーワードを理解するためにこのコマンドを試してほしい。

この部分は重要である。 人々が特定の話題で探して読者のパッケージをみつけるであろう。 キーワードは空白やカンマで区切る。

ほとんどのLispライブラリには、 `Author'と`Keywords'のヘッダコメント行が必要です。 残りのものは必要に応じて使います。 別の名前のヘッダ行があってもかまいません。 それらには標準的な意味はありませんが、害になることもありません。

ライブラリファイルの内容を分割するために形式を定めたコメントも使います。 それらを以下に示します。

`;;; Commentary:'
ライブラリの動作を説明する入門的なコメントを始める。 著作権表示の直後にきて、 `Change Log'、`History'、`Code'のいずれかのコメント行で終る。 このテキストはパッケージfinderが使うので、 その文脈で意味があるようにすること。

`;;; Documentation'
`;;; Commentary:'のかわりに使っているファイルもあるが、 `;;; Commentary:'のほうが好ましい。

`;;; Change Log:'
(変更履歴をライブラリに収める場合の) ライブラリファイルに収めた変更記録情報を始める。 Emacsで配布されるほとんどのLispファイルでは、 変更履歴はファイル`ChangeLog'に収めてあり、 ソースファイルには収めない。 それらのファイルには`;;; Change Log:'行はない。

`;;; Code:'
プログラムの実際のコードを始める。

`;;; filename ends here'
これは最終行(footer line)であり、ファイルの末尾に現れる。 その目的は、最終行が欠如していることでファイルが切り詰められていることが わかるようにするのである。

[ << ] [ >> ]           [表紙] [目次] [索引] [検索] [上端 / 下端]