Công ước bình luận của Emacs Lisp

Phụ lục D.7 của Hướng dẫn tham khảo Emacs Lisp đề cập đến một số mẹo nhận xét:

• Dấu chấm phẩy đơn ( ;) nên được sử dụng cho các bình luận nội tuyến.
• Dấu chấm phẩy kép ( ;;) nên được sử dụng cho nhận xét dòng.
• Ba dấu chấm phẩy ( ;;;) nên được sử dụng cho "các bình luận nên được coi là một tiêu đề theo chế độ phụ Outline".
• Dấu chấm phẩy gấp bốn lần ( ;;;;) nên được sử dụng cho các tiêu đề của các phần chính của chương trình.

Các trường hợp sử dụng dấu chấm phẩy đơn và kép là rõ ràng, nhưng dường như không có sự phân định rõ ràng giữa dấu chấm phẩy ba và bốn.

Đặc biệt, tài liệu tiêu chuẩn cho các gói Emacs được cung cấp bằng cách auto-insertsử dụng ba dấu chấm phẩy, không bao giờ tăng gấp bốn dấu chấm phẩy, ngay cả đối với các tiêu đề cấp cao nhất như tên tệp và các phần chính. Xem ví dụ dưới đây:

;;; 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

Các thực hành tốt nhất cho dấu chấm phẩy ba và bốn là gì?

Cập nhật

Nhờ câu trả lời của Stefan , tôi đã nộp báo cáo lỗi và đưa ra gợi ý sau:

Tôi đề nghị mô tả cho ba dấu chấm phẩy được thay đổi thành:

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.

Liên kết đến "Chế độ phụ phác thảo" trong hướng dẫn sử dụng Emacs sẽ hữu ích: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

Phần cho bốn dấu chấm phẩy có thể được tách ra.

Trên thực tế, các dấu chấm phẩy 3 và nhiều hơn tượng trưng cho các tiêu đề, trong đó càng nhiều dấu chấm phẩy bạn đặt càng sâu thì việc làm tổ của tiêu đề càng sâu. Vì vậy, nó sẽ trông giống như

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