From nobody Tue Feb 10 05:26:49 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1680602544; cv=none; d=zohomail.com; s=zohoarc; b=cd5Sn4O+YThsTACnlNtPyQA1qj1/RLVvrFqkgmTLxtwKZro6kshW6FmmcButCJuwpUmU0WC6qZdHye3YWVnlexxvuNAZkkkgviJrv+nRCri4NfJEc5QFYoM5PsQo54mAn8aDw71AS+uCaUcR2Rd23cC7gamNgtlT/CoPXCHmykY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1680602544; h=Content-Type:Content-Transfer-Encoding:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=SVe/N/ax7W4QoetsrZ8KmY8SLXzh4NVqEUZMHsSdtWk=; b=lRM6zieUBbE4+UcbEybjC4b+NK9a4polRwD0MtgHe3PqeIl6VBjYQfIDxOD/ZecvksKxpfOztzB7vW77S6dp1PcPDiaUiHWOrYwnzNXlq6BHl98rPpUYRJbiTbkvs6Xa/SyAPQwcJyy12/Wj+GKb1Sl3i60rY12NPHQm/xC1A/c= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1680602544709290.5949353220367; Tue, 4 Apr 2023 03:02:24 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-536-L8OvP12_Mz2R8B7bVk_6ag-1; Tue, 04 Apr 2023 06:02:20 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 46A9F85A5B1; Tue, 4 Apr 2023 10:02:17 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (unknown [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id BF121140EBF4; Tue, 4 Apr 2023 10:02:15 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 7E452194658D; Tue, 4 Apr 2023 10:02:15 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 27247194658C for ; Tue, 4 Apr 2023 10:02:14 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 170C9202701E; Tue, 4 Apr 2023 10:02:14 +0000 (UTC) Received: from localhost.localdomain (unknown [10.43.2.39]) by smtp.corp.redhat.com (Postfix) with ESMTP id B1FD72027061 for ; Tue, 4 Apr 2023 10:02:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1680602543; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=SVe/N/ax7W4QoetsrZ8KmY8SLXzh4NVqEUZMHsSdtWk=; b=jJTQQTOHiUhU6b8qGYjtlc9RxnXypIalEvHpS7LffBL9lSfd+GsXU+piM3NDGFvTsWE2bb LGcfO+X3X1Dt0QfgF7NboAQUHHZvuc2yh5aDbe8dsT1f9/wNraRYxsvS9wHmChzyY2nB+d 9BzNPXAkWsoFZvn06c/WXiseVozk3cM= X-MC-Unique: L8OvP12_Mz2R8B7bVk_6ag-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Michal Privoznik To: libvir-list@redhat.com Subject: [PATCH] coding style: Follow our own rule on comment style Date: Tue, 4 Apr 2023 12:02:10 +0200 Message-Id: <4077f8b20fac88d9671b08e71e65bc28a03e5559.1680602530.git.mprivozn@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.4 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 3.1 on 10.11.54.7 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1680602545064100001 Content-Type: text/plain; charset="utf-8"; x-default="true" In our coding style document we have examples of good and bad code, which we mark as: // Good // Bad respectively. But in the very same document we advocate for using C style of comments over C++. Follow our own advice and switch annotation to: /* Good */ /* Bad */ And while at it, align these annotations within their blocks for better readability. Signed-off-by: Michal Privoznik Reviewed-by: Peter Krempa --- docs/coding-style.rst | 76 +++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 92f6099d82..fe5fe9a906 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -161,24 +161,24 @@ a single space following them before the opening brac= ket. E.g. =20 :: =20 - if(foo) // Bad - if (foo) // Good + if(foo) /* Bad */ + if (foo) /* Good */ =20 Function implementations must **not** have any whitespace between the function name and the opening bracket. E.g. =20 :: =20 - int foo (int wizz) // Bad - int foo(int wizz) // Good + int foo (int wizz) /* Bad */ + int foo(int wizz) /* Good */ =20 Function calls must **not** have any whitespace between the function name and the opening bracket. E.g. =20 :: =20 - bar =3D foo (wizz); // Bad - bar =3D foo(wizz); // Good + bar =3D foo (wizz); /* Bad */ + bar =3D foo(wizz); /* Good */ =20 Function typedefs must **not** have any whitespace between the closing bracket of the function name and opening bracket of the @@ -186,16 +186,16 @@ arg list. E.g. =20 :: =20 - typedef int (*foo) (int wizz); // Bad - typedef int (*foo)(int wizz); // Good + typedef int (*foo) (int wizz); /* Bad */ + typedef int (*foo)(int wizz); /* Good */ =20 There must not be any whitespace immediately following any opening bracket, or immediately prior to any closing bracket. E.g. =20 :: =20 - int foo( int wizz ); // Bad - int foo(int wizz); // Good + int foo( int wizz ); /* Bad */ + int foo(int wizz); /* Good */ =20 Commas ------ @@ -206,8 +206,8 @@ syntax-check'. =20 :: =20 - call(a,b ,c);// Bad - call(a, b, c); // Good + call(a,b ,c); /* Bad */ + call(a, b, c); /* Good */ =20 When declaring an enum or using a struct initializer that occupies more than one line, use a trailing comma. That way, future edits @@ -225,11 +225,11 @@ C99 allows trailing commas, remember that JSON and XD= R do not. =20 enum { VALUE_ONE, - VALUE_TWO // Bad + VALUE_TWO /* Bad */ }; enum { VALUE_THREE, - VALUE_FOUR, // Good + VALUE_FOUR, /* Good */ }; =20 Semicolons @@ -243,10 +243,10 @@ not enforced, loop counters generally use post-increm= ent. =20 :: =20 - for (i =3D 0 ;i < limit ; ++i) { // Bad - for (i =3D 0; i < limit; i++) { // Good - for (;;) { // ok - while (1) { // Better + for (i =3D 0 ;i < limit ; ++i) { /* Bad */ + for (i =3D 0; i < limit; i++) { /* Good */ + for (;;) { /* ok */ + while (1) { /* Better */ =20 Empty loop bodies are better represented with curly braces and a comment, although use of a semicolon is not currently rejected. @@ -254,9 +254,9 @@ comment, although use of a semicolon is not currently r= ejected. :: =20 while ((rc =3D waitpid(pid, &st, 0) =3D=3D -1) && - errno =3D=3D EINTR); // ok + errno =3D=3D EINTR); /* ok */ while ((rc =3D waitpid(pid, &st, 0) =3D=3D -1) && - errno =3D=3D EINTR) { // Better + errno =3D=3D EINTR) { /* Better */ /* nothing */ } =20 @@ -271,19 +271,19 @@ single-\ *statement* loop: each has only one *line* i= n its body. =20 :: =20 - while (expr) // single line body; {} is optional + while (expr) /* single line body; {} is optional */ single_line_stmt(); =20 :: =20 while (expr(arg1, - arg2)) // indentation makes it obvious it is single lin= e, - single_line_stmt(); // {} is optional (not enforced either way) + arg2)) /* indentation makes it obvious it is single l= ine, */ + single_line_stmt(); /* {} is optional (not enforced either way) */ =20 :: =20 while (expr1 && - expr2) { // multi-line, at same indentation, {} required + expr2) { /* multi-line, at same indentation, {} require= d */ single_line_stmt(); } =20 @@ -295,7 +295,7 @@ braces), thinking it is already a multi-statement loop: =20 :: =20 - while (true) // BAD! multi-line body with no braces + while (true) /* BAD! multi-line body with no braces */ /* comment... */ single_line_stmt(); =20 @@ -303,7 +303,7 @@ Do this instead: =20 :: =20 - while (true) { // Always put braces around a multi-line body. + while (true) { /* Always put braces around a multi-line body.= */ /* comment... */ single_line_stmt(); } @@ -325,8 +325,8 @@ To reiterate, don't do this: =20 :: =20 - if (expr) // BAD: no braces around... - while (expr_2) { // ... a multi-line body + if (expr) /* BAD: no braces around... */ + while (expr_2) { /* ... a multi-line body */ ... } =20 @@ -356,11 +356,11 @@ longer, multi-line block be the ``else`` block. ... } else - x =3D y; // BAD: braceless "else" with braced "then", - // and short block last + x =3D y; /* BAD: braceless "else" with braced "then", + * and short block last */ =20 if (expr) - x =3D y; // BAD: braceless "if" with braced "else" + x =3D y; /* BAD: braceless "if" with braced "else" */ else { ... ... @@ -375,7 +375,7 @@ rather than after the more involved block: :: =20 if (!expr) { - x =3D y; // putting the smaller block first is more readable + x =3D y; /* putting the smaller block first is more readable */ } else { ... ... @@ -403,19 +403,19 @@ itself. =20 void foo(int a, int b) - { // correct - function body + { /* correct - function body */ int 2d[][] =3D { - { // correct - complex initialization + { /* correct - complex initialization */ 1, 2, }, }; if (a) - { // BAD: compound brace on its own line + { /* BAD: compound brace on its own line */ do_stuff(); } - { // correct - nested scope + { /* correct - nested scope */ int tmp; - if (a < b) { // correct - hanging brace + if (a < b) { /* correct - hanging brace */ tmp =3D b; b =3D a; a =3D tmp; @@ -601,7 +601,7 @@ calling another function. =20 x =3D y + 20; =20 - char *z =3D NULL; // <=3D=3D=3D + char *z =3D NULL; /* <=3D=3D=3D */ ... } =20 --=20 2.39.2