From patchwork Thu Aug 4 09:37:36 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 9263191 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 23A356048B for ; Thu, 4 Aug 2016 09:40:11 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1526F28335 for ; Thu, 4 Aug 2016 09:40:11 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0850228391; Thu, 4 Aug 2016 09:40:11 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 7C54D28335 for ; Thu, 4 Aug 2016 09:40:10 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bVF65-0004Z7-4P; Thu, 04 Aug 2016 09:37:49 +0000 Received: from mail6.bemta5.messagelabs.com ([195.245.231.135]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bVF63-0004Yw-Hs for xen-devel@lists.xenproject.org; Thu, 04 Aug 2016 09:37:47 +0000 Received: from [85.158.139.211] by server-6.bemta-5.messagelabs.com id 97/71-29022-AEC03A75; Thu, 04 Aug 2016 09:37:46 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrJLMWRWlGSWpSXmKPExsXitHSDve4rnsX hBqvuill83zKZyYHR4/CHKywBjFGsmXlJ+RUJrBkbHk9kLbjGU7H74DuWBsYTXF2MnBwSAv4S z54sZASx2QT0JOYd/8rSxcjBISKgInF7r0EXIxcHs8AmJonVZ3ewgdQICwRIPPxzEsxmAap5/ O0dM4jNK+Ah8bPtMhvETDmJ88d/gsWFBFQlFj84yg5RIyhxcuYTFhCbWUBC4uCLF8wQ9dwSt0 9PZZ7AyDMLSdksJGULGJlWMWoUpxaVpRbpGprqJRVlpmeU5CZm5ugaGpjq5aYWFyemp+YkJhX rJefnbmIEBgkDEOxgbNjueYhRkoNJSZT3B9ficCG+pPyUyozE4oz4otKc1OJDjDIcHEoSvAe5 gXKCRanpqRVpmTnAcIVJS3DwKInwbgJJ8xYXJOYWZ6ZDpE4xKkqJ83IBg1xIACSRUZoH1waLk UuMslLCvIxAhwjxFKQW5WaWoMq/YhTnYFQS5j0MMp4nM68EbvoroMVMQItPGCwAWVySiJCSam CUmtKXprfngtpGk9eMSzSdXNqTdXa+44u7EN+2ZrnIrwUfGgKbVZ6IiZ9uTFx/55zywzVV6dq feFa/qp96vJ3pnlnG7AdS36799VU6pdWQc3hC4qLnxcX/4resVbx54fGrkL6FGzke7Zau1ah5 d9QotOPtjyvG96ritm21m2jf6mDRHFcrEBGvxFKckWioxVxUnAgATaqMiYwCAAA= X-Env-Sender: prvs=017aa8cf0=George.Dunlap@citrix.com X-Msg-Ref: server-15.tower-206.messagelabs.com!1470303464!40838624!1 X-Originating-IP: [66.165.176.63] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: VHJ1c3RlZCBJUDogNjYuMTY1LjE3Ni42MyA9PiAzMDYwNDg=\n, received_headers: No Received headers X-StarScan-Received: X-StarScan-Version: 8.77; banners=-,-,- X-VirusChecked: Checked Received: (qmail 61374 invoked from network); 4 Aug 2016 09:37:46 -0000 Received: from smtp02.citrix.com (HELO SMTP02.CITRIX.COM) (66.165.176.63) by server-15.tower-206.messagelabs.com with RC4-SHA encrypted SMTP; 4 Aug 2016 09:37:46 -0000 X-IronPort-AV: E=Sophos;i="5.28,470,1464652800"; d="scan'208";a="377411132" From: George Dunlap To: Date: Thu, 4 Aug 2016 10:37:36 +0100 Message-ID: <1470303456-13210-1-git-send-email-george.dunlap@citrix.com> X-Mailer: git-send-email 2.1.4 MIME-Version: 1.0 X-DLP: MIA2 Cc: Stefano Stabellini , Wei Liu , Andrew Cooper , Tim Deegan , George Dunlap , Jan Beulich , Ian Jackson Subject: [Xen-devel] [PATCH] CODING_STYLE: Allow single-sentence comments without full stops X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP One of the common ways in which contributors trip up over the CODING_STYLE guides is by not putting a full stop at the end of a comment when there is only a single sentence. Calling these out is a waste of everybody's time: The full stop at the end of a comment with a single sentence (or a single phrase) adds absolutely nothing to the legibility of the code. Modify CODING_STYLE to allow comments with a single sentence or sentence fragment to either have a full stop or not, while making it clear that comments with multiple sentences must have a full stop at the end of each sentence. Signed-off-by: George Dunlap Acked-by: Ian Jackson --- CC: Andrew Cooper CC: Ian Jackson CC: Jan Beulich CC: Konrad Wilk CC: Stefano Stabellini CC: Tim Deegan CC: Wei Liu --- CODING_STYLE | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CODING_STYLE b/CODING_STYLE index 95842e3..4c3b53a 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -93,7 +93,9 @@ Comments Only C style /* ... */ comments are to be used. C++ style // comments should not be used. Multi-word comments should begin with a capital -letter and end with a full stop. +letter. Comments containing a single sentence may end with a full +stop; comments containing several sentences must have a full stop +after each sentence. Multi-line comment blocks should start and end with comment markers on separate lines and each line should begin with a leading '*'.