Konvensi komentar Emacs Lisp

17

Lampiran Panduan Referensi Emacs Lisp D.7 menyebutkan beberapa tips komentar:

  • Tanda titik koma tunggal ( ;) harus digunakan untuk komentar sebaris.
  • Tanda titik koma ganda ( ;;) harus digunakan untuk komentar baris.
  • Tiga titik koma ( ;;;) harus digunakan untuk "komentar yang harus dianggap sebagai judul dengan mode minor Garis Besar".
  • Titik koma empat kali lipat ( ;;;;) harus digunakan untuk judul bagian utama dari suatu program.

Kasus penggunaan titik koma tunggal dan ganda jelas, tetapi tampaknya tidak ada penggambaran yang tajam antara titik koma tiga dan empat.

Secara khusus, dokumentasi standar untuk paket Emacs disediakan dengan auto-insertmenggunakan tiga titik koma, tidak pernah empat kali lipat titik koma, bahkan untuk judul tingkat tertinggi seperti nama file dan bagian utama. Lihat contoh di bawah ini:

;;; test.el --- A test file.                         -*- lexical-binding: t; -*-

;; Copyright (C) 2016

;; Author:  John Smith
;; Keywords: 

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; 

;;; Code:



(provide 'test)
;;; test.el ends here

Apa praktik terbaik untuk titik koma tiga dan empat?

Memperbarui

Berkat jawaban Stefan , saya telah mengajukan laporan bug dan membuat saran berikut:

Saya menyarankan agar deskripsi untuk tiga titik koma diubah menjadi:

Comments that start with three semicolons, ‘;;;’, are considered
top-level headings by Outline minor mode.

Four or more semicolons can be used as subheadings in hierarchical
fashion. E.g.

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading

These comments should be used to break Emacs Lisp code into sections.

Tautan ke "Outline minor mode" di manual Emacs akan bermanfaat: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

Bagian untuk empat titik koma dapat dihilangkan.

Tianxiang Xiong
sumber
Lihatlah sumber Emacs ( grep -r '^;;;; ' lisp) untuk mendapatkan inspirasi.
sds
@sds yang menghasilkan beberapa aplikasi non-standar ;;;; dalam sumber kanonik;)
Tyler
Itulah yang saya maksud - rekomendasi 4 titik koma ini tidak dapat dianggap terlalu serius, OTOH, kita juga harus melihat file timestamp - hal-hal yang tidak standar ini bisa usang.
sds

Jawaban:

13

Sebenarnya, 3-dan-lebih semi-titik dua berdiri untuk pos, di mana semakin banyak semi-titik dua Anda menempatkan semakin dalam bersarang dari pos. Jadi seharusnya terlihat seperti

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Stefan
sumber
Itu tampaknya menjadi praktik umum, tetapi berbeda dari konvensi yang tercantum dalam manual Elisp yang terkait dalam pertanyaan. Apakah itu bug dalam manual?
Tyler
3
Ini bukan hanya soal latihan. Begitulah cara emacs-lisp-modemengkonfigurasi outline-minor-mode. Saya sarankan Anda melaporkan ini sebagai bug dokumentasi (saya pikir dokumen tidak jelas lebih dari salah, tetapi hasil akhirnya sama).
Stefan
Saya telah mengirim laporan bug, dan menawarkan saran untuk mengubah dokumentasi ke hal lain. Saya melihat bahwa saya bisa mendapatkan sumber TexInfo untuk manual; apakah ada repositori yang bisa saya klonkan dan buat permintaan tarik?
Tianxiang Xiong
@TianxiangXiong: Tentu saja, dokumen ini adalah bagian dari kode sumber Emacs, sehingga Anda dapat mengkloning git://git.sv.gnu.org/emacs.gitdan kemudian mengirim tambalan melalui M-x report-emacs-bug.
Stefan
Untuk referensi, berikut adalah konvensi Common Lisp . Jika Emacs Lisp benar-benar menggunakan 3 titik koma untuk heading tetapi kemudian 4 titik koma untuk heading yang kurang menonjol, itu tampaknya tidak logis dan bertentangan dengan apa yang saya lihat di CL dan lisps lainnya. Mungkin itu hanya lebih cocok untuk judul gaya org-mode sehingga mereka pergi dengan itu untuk elisp juga.
Lassi