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-insert
menggunakan 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.
grep -r '^;;;; ' lisp
) untuk mendapatkan inspirasi.Jawaban:
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
sumber
emacs-lisp-mode
mengkonfigurasioutline-minor-mode
. Saya sarankan Anda melaporkan ini sebagai bug dokumentasi (saya pikir dokumen tidak jelas lebih dari salah, tetapi hasil akhirnya sama).git://git.sv.gnu.org/emacs.git
dan kemudian mengirim tambalan melaluiM-x report-emacs-bug
.