From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Conventions for writing comments Date: Mon, 06 Oct 2014 09:09:07 -0400 Message-ID: References: <86h9zhh7w4.fsf@example.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1412600974 16703 80.91.229.3 (6 Oct 2014 13:09:34 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 6 Oct 2014 13:09:34 +0000 (UTC) Cc: emacs-devel@gnu.org To: Sebastien Vauban Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 06 15:09:25 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Xb82W-00086A-40 for ged-emacs-devel@m.gmane.org; Mon, 06 Oct 2014 15:09:24 +0200 Original-Received: from localhost ([::1]:51813 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xb82V-0007W8-Dk for ged-emacs-devel@m.gmane.org; Mon, 06 Oct 2014 09:09:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58686) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xb82M-0007VT-P8 for emacs-devel@gnu.org; Mon, 06 Oct 2014 09:09:20 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xb82G-0002Z2-Ry for emacs-devel@gnu.org; Mon, 06 Oct 2014 09:09:14 -0400 Original-Received: from ironport2-out.teksavvy.com ([206.248.154.181]:30446) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xb82G-0002Xj-Ol for emacs-devel@gnu.org; Mon, 06 Oct 2014 09:09:08 -0400 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: ArYGAIDvNVNFxKjo/2dsb2JhbABZgwY7gw/APYEXF3SCJQEBAQECAVYjBQsLDiYSFBgNJIgECA3SDBMEjnoHhDgEqRmBaoNMIQ X-IPAS-Result: ArYGAIDvNVNFxKjo/2dsb2JhbABZgwY7gw/APYEXF3SCJQEBAQECAVYjBQsLDiYSFBgNJIgECA3SDBMEjnoHhDgEqRmBaoNMIQ X-IronPort-AV: E=Sophos;i="4.97,753,1389762000"; d="scan'208";a="91781516" Original-Received: from 69-196-168-232.dsl.teksavvy.com (HELO pastel.home) ([69.196.168.232]) by ironport2-out.teksavvy.com with ESMTP/TLS/DHE-RSA-AES256-SHA; 06 Oct 2014 09:09:07 -0400 Original-Received: by pastel.home (Postfix, from userid 20848) id 6062285CC; Mon, 6 Oct 2014 09:09:07 -0400 (EDT) In-Reply-To: <86h9zhh7w4.fsf@example.com> (Sebastien Vauban's message of "Mon, 06 Oct 2014 11:20:11 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 206.248.154.181 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:175011 Archived-At: > I have a small question about conventions for writing comments... Can > I consider the following to be the rule? The main documentation we follow for coding style is the GNU Coding Standard (https://www.gnu.org/prep/standards/html_node/Comments.html) which says, among other things: Also, please write complete sentences and capitalize the first word. > - Otherwise (like ";; pattern found"), comments must begin with a small > letter and don't end with a dot. I prefer to capitalize and punctuate this as well (BTW: this is also a sentence). Note that a lot of code in Emacs does not follow the convention, because we're not strict enough about enforcing it. Stefan