From nobody Sat Apr 20 02:09:33 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) client-ip=66.175.222.12; envelope-from=bounce+27952+46933+1787277+3901457@groups.io; helo=web01.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46933+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567708706; cv=none; d=zoho.com; s=zohoarc; b=TU4cnJIswiDfi4bSte/+S9Iwfd3/DHQZv+g6RRzzD6/Q+4Ip6ak2oogmX8ieNwr973llPuSio4S/ZVKPBEf3DToVj8Rt7oTmBBhmtOPNVigW0OVvcIn61oDgmc6iXGDYXUrRwQzqso4Q0RH5gMCfTBoP2uJjM8V15acYRYFYANE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567708706; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Id:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To:ARC-Authentication-Results; bh=tRoUkjypHUALc+ny6stKSOBCCGRrJ/n7wAGsb/dNvls=; b=hZzbWL3CCFiJBBarMSrnLImSjDEvznkw0Ad9h03IiqrH8OaCEoo75bYFWr/2KQ+Qwof0kUCNs2iU2kHtsfR9LlwufmC+2w0tfB1cKn3tpdKPrur8KNixkXgb0Wd4fhz9ukCGOwUu0CuVsZzWjXQtUI9ZrRhwCwBf0uFeqcef664= ARC-Authentication-Results: i=1; mx.zoho.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46933+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) header.from= Received: from web01.groups.io (web01.groups.io [66.175.222.12]) by mx.zohomail.com with SMTPS id 1567708706630510.1226751137598; Thu, 5 Sep 2019 11:38:26 -0700 (PDT) Return-Path: X-Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Thu, 05 Sep 2019 11:38:25 -0700 X-Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 3DFBA898106; Thu, 5 Sep 2019 18:38:25 +0000 (UTC) X-Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-133.ams2.redhat.com [10.36.116.133]) by smtp.corp.redhat.com (Postfix) with ESMTP id D75375D6A3; Thu, 5 Sep 2019 18:38:23 +0000 (UTC) From: "Laszlo Ersek" To: edk2-devel-groups-io Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran Subject: [edk2-devel] [PATCH edk2-CCSS 1/3] comments: remove "Horror Vacui" rule Date: Thu, 5 Sep 2019 20:38:18 +0200 Message-Id: <20190905183820.10312-2-lersek@redhat.com> In-Reply-To: <20190905183820.10312-1-lersek@redhat.com> References: <20190905183820.10312-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.67]); Thu, 05 Sep 2019 18:38:25 +0000 (UTC) Precedence: Bulk List-Unsubscribe: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,lersek@redhat.com Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1567708706; bh=AiM8n3SY+E88Yml2tgvtNPE6OCc1njUO5DRXKS/cSzE=; h=Cc:Date:From:Reply-To:Subject:To; b=CWzKETDnJD7wQdPgENyGf4q6BZGMGV4TbcbC4mECrCrZDCzyc9VSBcUUFR0KgWqUEYr LhdllsKOU+up9TgOQdwpKyD6bvJnG4DWOLxsdFgRhT4yGWjF6ZaIOH6p1VlOYv5fktuK0 O84uEuek/Sy1GlSX9KRl97QkbrNWEYcJRQo= X-ZohoMail-DKIM: pass (identity @groups.io) Content-Type: text/plain; charset="utf-8" The rule about avoiding comments in C code where the opening comment characters are alone on a line conflicts with everyday edk2 practice -- we use comments like // // If the total number of lines in the popup is zero, then ASSERT() // all the time. This comment style is actively enforced by reviewers and maintainers. Remove the rule in order for the CCS to match reality. Cc: Andrew Fish Cc: Leif Lindholm Cc: Michael D Kinney Cc: Rebecca Cran Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=3D607 Signed-off-by: Laszlo Ersek Reviewed-by: Leif Lindholm --- 6_documenting_software/62_comments.md | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/6_documenting_software/62_comments.md b/6_documenting_software= /62_comments.md index 208ce346f607..ae04e008a1eb 100644 --- a/6_documenting_software/62_comments.md +++ b/6_documenting_software/62_comments.md @@ -66,23 +66,7 @@ not behave the same. Banners can be useful to highlight logical divisions within a file; such as before vital sections. This type of usage should be minimized. =20 -### 6.2.3 Avoid comments where the opening comment characters are alone on= a line. - -``` -/* - * VIOLATION: Horror Vacui -*/ -``` - -or - -```c -// -// VIOLATION: Horror Vacui -// -``` - -### 6.2.4 Do not include jokes or obtuse references in comments. +### 6.2.3 Do not include jokes or obtuse references in comments. =20 ``` "Out of cheese error! Redo from start." --=20 2.19.1.3.g30247aa5d201 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#46933): https://edk2.groups.io/g/devel/message/46933 Mute This Topic: https://groups.io/mt/33157542/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Sat Apr 20 02:09:33 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) client-ip=66.175.222.12; envelope-from=bounce+27952+46934+1787277+3901457@groups.io; helo=web01.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46934+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567708708; cv=none; d=zoho.com; s=zohoarc; b=XXMpd9zwKdoG9fg8CrA6w6nmqB+BW/XYbxTSiGgjrqKgsrpsHARr7wpknM2pajUo9eHppalFsTch6vPbfWCTw16dubWAoWBajs8FXIKY982F87GgXMBS9AW7Fz4xaHHaLd0yeK/SURF33HR66la8JfQeCVv1O28R7qL1fz5H180= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567708708; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Id:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To:ARC-Authentication-Results; bh=z7C41hFoNzU4DUMNRjgUhQVDCMzoZKywX55fDWKSd/I=; b=fWWrRPqkNe5TxEOu9B455OXa/PgD2VjsZVLnFnJ4ormbANsUoIGRj9px5casYy4rDAJQ4VPI6M/1Y6kFYzGpbTo+bFbrj+4G2mXF9+brG8VibpITHLECECffrPIHv+QdauXdewiibUqTRtkPg8/jv4FtYGMFFZzVv0KwC81l68A= ARC-Authentication-Results: i=1; mx.zoho.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46934+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) header.from= Received: from web01.groups.io (web01.groups.io [66.175.222.12]) by mx.zohomail.com with SMTPS id 1567708708311117.18407627818203; Thu, 5 Sep 2019 11:38:28 -0700 (PDT) Return-Path: X-Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Thu, 05 Sep 2019 11:38:27 -0700 X-Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id E16CBC04D312; Thu, 5 Sep 2019 18:38:26 +0000 (UTC) X-Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-133.ams2.redhat.com [10.36.116.133]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8CB245D6A3; Thu, 5 Sep 2019 18:38:25 +0000 (UTC) From: "Laszlo Ersek" To: edk2-devel-groups-io Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran Subject: [edk2-devel] [PATCH edk2-CCSS 2/3] comments: restrict and clarify applicability of "/*" comments Date: Thu, 5 Sep 2019 20:38:19 +0200 Message-Id: <20190905183820.10312-3-lersek@redhat.com> In-Reply-To: <20190905183820.10312-1-lersek@redhat.com> References: <20190905183820.10312-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.31]); Thu, 05 Sep 2019 18:38:26 +0000 (UTC) Precedence: Bulk List-Unsubscribe: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,lersek@redhat.com Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1567708708; bh=+ZfZjmkXZ0EQ6DmlvB3xd1yV/0h4cUFkVecYK5LmEYc=; h=Cc:Date:From:Reply-To:Subject:To; b=ucmsgf9huZ7cBjH6WM9xHCPmKJj9kjwbgaGfAADUFeLGMqA0k8vbaBkm5RqLlkCzmsm aX5sdlocp04ChvljOUSTm+nNmT4KNs1f30MBCEjHS7umyN0gdarege+PkjcKkXDrXgPb/ CuqOqPZmxHsBO21YZ9pRjbRpEdpYK1CPqqs= X-ZohoMail-DKIM: pass (identity @groups.io) Content-Type: text/plain; charset="utf-8" Section "6.2 Comments" seems to permit "/*" for multi-line comments in general. That's incorrect; "/*" comments are permitted only for a subset of multi-line comments (namely Doxygen-style file and function header comment blocks). Update the rule accordingly. Cc: Andrew Fish Cc: Leif Lindholm Cc: Michael D Kinney Cc: Rebecca Cran Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=3D607 Signed-off-by: Laszlo Ersek Reviewed-by: Leif Lindholm Reviewed-by: Philippe Mathieu-Daude --- 6_documenting_software/62_comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/6_documenting_software/62_comments.md b/6_documenting_software= /62_comments.md index ae04e008a1eb..5feb5cee2055 100644 --- a/6_documenting_software/62_comments.md +++ b/6_documenting_software/62_comments.md @@ -54,7 +54,7 @@ minimal familiarity with the code. Clarity is important, = but one should also strive for terse and concise comments. One should be able to see both the comment, and the code being commented on, on the same screen. =20 -### 6.2.1 Only use C style, "/*", comments for multi-line comments and on = the same line as pre-processor directives. +### 6.2.1 Only use C style, "/*", comments on the same line as pre-process= or directives, and in Doxygen-style file and function header comment blocks. =20 Compile can vary in their support for use of `//` in preprocessor directiv= es (e.g. `#define`). Note that the mixing of `/* ... */` and `//` is not hand= led --=20 2.19.1.3.g30247aa5d201 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#46934): https://edk2.groups.io/g/devel/message/46934 Mute This Topic: https://groups.io/mt/33157543/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Sat Apr 20 02:09:33 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) client-ip=66.175.222.12; envelope-from=bounce+27952+46935+1787277+3901457@groups.io; helo=web01.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46935+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567708709; cv=none; d=zoho.com; s=zohoarc; b=XrsSPGVyc8HalLs9W03WY8wbtrwUkv9RqAahCA4zC2iTBe6kuk/QtErJqBGhQT6yZNDdliYuZ3nQexPPJMN9ne9vRrQKR0THEkhvgs1M0nP9KuPc1M2zTCtWAK48u2aqz4wB/kOLteRHgbNe99D808ETgPsI09CMjLHw87j+MRE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567708709; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Id:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To:ARC-Authentication-Results; bh=ODQcbXI8gvb4acuf4qsWpZhESe2Cn2auNk3lp5cf2mQ=; b=TG/7joSEetP1eR2Ql1+lAS/uaBZtglfu1JffybfKCCoQoqoYDYEjnGd1oFM6M9OYQncloOk0vr0PxzPbwYuU3WvIzFhAvo+3wC1QRmvg0ZsuGjr8QjcWkOXOkpOsiL7iFHd3fYnMCngN1k7LdaA2b0bMWTJtYZrHQ6nhDqFvyxY= ARC-Authentication-Results: i=1; mx.zoho.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46935+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) header.from= Received: from web01.groups.io (web01.groups.io [66.175.222.12]) by mx.zohomail.com with SMTPS id 1567708709811249.43074264637073; Thu, 5 Sep 2019 11:38:29 -0700 (PDT) Return-Path: X-Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Thu, 05 Sep 2019 11:38:28 -0700 X-Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 926601DA2; Thu, 5 Sep 2019 18:38:28 +0000 (UTC) X-Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-133.ams2.redhat.com [10.36.116.133]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3FAF15D712; Thu, 5 Sep 2019 18:38:27 +0000 (UTC) From: "Laszlo Ersek" To: edk2-devel-groups-io Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran Subject: [edk2-devel] [PATCH edk2-CCSS 3/3] must comment: add rule for documenting spurious variable assignments Date: Thu, 5 Sep 2019 20:38:20 +0200 Message-Id: <20190905183820.10312-4-lersek@redhat.com> In-Reply-To: <20190905183820.10312-1-lersek@redhat.com> References: <20190905183820.10312-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.71]); Thu, 05 Sep 2019 18:38:28 +0000 (UTC) Precedence: Bulk List-Unsubscribe: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,lersek@redhat.com Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1567708709; bh=MmG4QhObsIxgJzt6Xqyc1YcfuxYSPiuCGo5WZvszigA=; h=Cc:Date:From:Reply-To:Subject:To; b=qB8m8RlG8Bz3M8hIXuss6dDiG+Os54lwq+gz3lFOEX/01xsPwpulHTjaEN/c3qK12zB p5ZOS7LsPYet337KAVX5n/zIz1Ee73Gi+97sBMm4QvHWXv2H0Z8eWzbOayTrRziB/OW3U lEGnuMPRgyT2UQiU8liiBICO6LesZlHXomU= X-ZohoMail-DKIM: pass (identity @groups.io) Content-Type: text/plain; charset="utf-8" Problem statement from Ard: > Sometimes, the GCC compiler warns about variables potentially being used > without having been initialized, while visual inspection reveals that > this is impossible. In such cases, we need to initialize such a variable > to an arbitrary value only to avoid breaking the build, given our policy > to treat warnings as errors. In such cases we generally use LocalIntegerVariable =3D 0; and LocalPointerVariable =3D NULL; which takes care of the incorrect warning. However, it also makes the human analysis of any subsequent logic harder, because it suggests that assigning that specific zero or NULL value to the local variable is *required* by the subsequent logic. In order to highlight such assignments, whose sole purpose is to suppress invalid "use before init" warnings from compilers or static analysis tools, we should mandate comments such as: // // set LocalVariable to suppress incorrect compiler/analyzer warnings // LocalVariable =3D 0; (Magic values such as 0xDEADBEEF, which would obviate the necessity of explicit comments, have been considered, and rejected for stylistic reasons.) Cc: Andrew Fish Cc: Leif Lindholm Cc: Michael D Kinney Cc: Rebecca Cran Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=3D607 Signed-off-by: Laszlo Ersek Reviewed-by: Leif Lindholm Reviewed-by: Philippe Mathieu-Daude --- 6_documenting_software/64_what_you_must_comment.md | 39 ++++++++++++++++++= ++ README.md | 1 + 2 files changed, 40 insertions(+) diff --git a/6_documenting_software/64_what_you_must_comment.md b/6_documen= ting_software/64_what_you_must_comment.md index abb2114bf5bc..9e51c2e45816 100644 --- a/6_documenting_software/64_what_you_must_comment.md +++ b/6_documenting_software/64_what_you_must_comment.md @@ -58,3 +58,42 @@ instance differs. =20 When possible, you should also list the requirements that are satisfied by= the code. + +### 6.4.6 Comment spurious variable assignments. + +A compiler or static code analyzer may warn that an object with automatic = or +allocated storage duration is read without having been initialized, while +visual inspection reveals that this is impossible. + +In order to suppress such a warning (which is emitted due to invalid data = flow +analysis), developers explicitly assign the affected object the value to w= hich +the same object would be initialized automatically, had the object static +storage duration, and no initializer. (The value assigned could be arbitra= ry; +the above-mentioned value is chosen for stylistic reasons.) For example: + +```c +UINTN LocalIntegerVariable; +VOID *LocalPointerVariable; + +LocalIntegerVariable =3D 0; +LocalPointerVariable =3D NULL; +``` + +This kind of assignment is difficult to distinguish from assignments where= the +initial value of an object is meaningful, and is consumed by other code wi= thout +an intervening assignment. Therefore, each such assignment must be documen= ted, +as follows: + +```c +UINTN LocalIntegerVariable; +VOID *LocalPointerVariable; + +// +// set LocalIntegerVariable to suppress incorrect compiler/analyzer warnin= gs +// +LocalIntegerVariable =3D 0; +// +// set LocalPointerVariable to suppress incorrect compiler/analyzer warnin= gs +// +LocalPointerVariable =3D NULL; +``` diff --git a/README.md b/README.md index e26133540368..0648819f0d3a 100644 --- a/README.md +++ b/README.md @@ -113,3 +113,4 @@ Copyright (c) 2006-2017, Intel Corporation. All rights = reserved. | 2.2 | Convert to Gitbook = = | June 2017 | | | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=3D425) = [CCS] clarify line breaking and indentation requirements for multi-line fun= ction calls | | | | [#1656](https://bugzilla.tianocore.org/show_bug.cgi?id=3D1656= ) Update all Wiki pages for the BSD+Patent license change with SPDX identif= iers | | +| | [#607](https://bugzilla.tianocore.org/show_bug.cgi?id=3D607) = Document code comment requirements for spurious variable assignments = | | --=20 2.19.1.3.g30247aa5d201 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#46935): https://edk2.groups.io/g/devel/message/46935 Mute This Topic: https://groups.io/mt/33157544/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-