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


17

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.


Xem qua các nguồn Emacs ( grep -r '^;;;; ' lisp) để tìm cảm hứng.
sds

@sds bật lên một vài ứng dụng không chuẩn của ;;;; trong các nguồn chính tắc;)
Tyler

Đó là điều tôi muốn nói - khuyến nghị 4 dấu chấm phẩy này không thể quá nghiêm trọng, OTOH, người ta cũng nên nhìn vào dấu thời gian của tệp - những điều không chuẩn này có thể bị lỗi thời.
sds

Câu trả lời:


13

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

Đó dường như là cách làm phổ biến, nhưng khác với các quy ước được liệt kê trong hướng dẫn Elisp được liên kết trong câu hỏi. Đó có phải là một lỗi trong hướng dẫn?
Tyler

3
Đó không chỉ là một câu hỏi thực hành. Đó là cách emacs-lisp-modecấu hình outline-minor-mode. Tôi đề nghị bạn báo cáo đây là lỗi tài liệu (tôi nghĩ rằng tài liệu không rõ ràng hơn sai, nhưng kết quả cuối cùng là như nhau).
Stefan

Tôi đã gửi một báo cáo lỗi, và đưa ra một đề nghị để thay đổi tài liệu này sang một cái gì đó khác. Tôi thấy rằng tôi có thể lấy nguồn TexInfo cho hướng dẫn; Có một kho lưu trữ mà tôi có thể sao chép và thực hiện một yêu cầu kéo không?
Tianxiang Xiong

@TianxiangXiong: Tất nhiên, tài liệu là một phần của mã nguồn của Emacs, vì vậy bạn có thể sao chép git://git.sv.gnu.org/emacs.gitvà sau đó gửi một bản vá qua M-x report-emacs-bug.
Stefan

Để tham khảo, đây là các quy ước Lisp chung . Nếu Emacs Lisp thực sự sử dụng 3 dấu chấm phẩy cho một tiêu đề nhưng sau đó là 4 dấu chấm phẩy cho một tiêu đề ít nổi bật hơn, điều đó có vẻ phi logic và trái ngược với những gì tôi đã thấy trong CL và các lisps khác. Có lẽ nó chỉ đơn giản là phù hợp hơn cho các tiêu đề kiểu chế độ org, vì vậy họ cũng đã sử dụng nó cho phù hợp.
Lassi
Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.