From patchwork Fri Nov 16 15:13:07 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ilya Maximets X-Patchwork-Id: 998997 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=samsung.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=samsung.com header.i=@samsung.com header.b="SZe7zDAK"; dkim-atps=neutral Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 42xMF30FQdz9s47 for ; Sat, 17 Nov 2018 02:13:26 +1100 (AEDT) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id F31B5B63; Fri, 16 Nov 2018 15:13:23 +0000 (UTC) X-Original-To: ovs-dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 900E1B08 for ; Fri, 16 Nov 2018 15:13:22 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mailout1.w1.samsung.com (mailout1.w1.samsung.com [210.118.77.11]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 3DD01825 for ; Fri, 16 Nov 2018 15:13:21 +0000 (UTC) Received: from eucas1p2.samsung.com (unknown [182.198.249.207]) by mailout1.w1.samsung.com (KnoxPortal) with ESMTP id 20181116151319euoutp01dd496a8609b7d806057af3a42f6ebe08~no4doGq3-0120601206euoutp01x for ; Fri, 16 Nov 2018 15:13:19 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 mailout1.w1.samsung.com 20181116151319euoutp01dd496a8609b7d806057af3a42f6ebe08~no4doGq3-0120601206euoutp01x DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=samsung.com; s=mail20170921; t=1542381199; bh=K07biqOcnFryXzB6v2DpaL2uNdHRydnzFRdoqwEvpTo=; h=From:To:Cc:Subject:Date:References:From; b=SZe7zDAK4tjWQrOaf5TcdxkycH/I6c6DxpPJYwzwpLDoNR5r2AC+8HRhNv0WewFJy 1ioNc1o2tSGUTC2uTEBJpbzCrYsZ78wyTsdvcyjXZulGX/AgXf89HAhoRQyOFrL5QG 2erV4PX4pGTkpnv2UVCAh5ujcNgxX1KywU1w0d8s= Received: from eusmges3new.samsung.com (unknown [203.254.199.245]) by eucas1p1.samsung.com (KnoxPortal) with ESMTP id 20181116151318eucas1p1738671f772faad9b75da311df803e54c~no4dJp7Gq0641106411eucas1p1V; Fri, 16 Nov 2018 15:13:18 +0000 (GMT) Received: from eucas1p2.samsung.com ( [182.198.249.207]) by eusmges3new.samsung.com (EUCPMTA) with SMTP id 48.B5.04806.E8EDEEB5; Fri, 16 Nov 2018 15:13:18 +0000 (GMT) Received: from eusmtrp1.samsung.com (unknown [182.198.249.138]) by eucas1p2.samsung.com (KnoxPortal) with ESMTPA id 20181116151318eucas1p28bf7261e04c227447600879d912cc31d~no4cc-k4X3160231602eucas1p2y; Fri, 16 Nov 2018 15:13:18 +0000 (GMT) Received: from eusmgms1.samsung.com (unknown [182.198.249.179]) by eusmtrp1.samsung.com (KnoxPortal) with ESMTP id 20181116151317eusmtrp1147fe59702de438c4172c84399256ffa~no4cOupLu0252602526eusmtrp13; Fri, 16 Nov 2018 15:13:17 +0000 (GMT) X-AuditID: cbfec7f5-34dff700000012c6-5c-5beede8e4392 Received: from eusmtip1.samsung.com ( [203.254.199.221]) by eusmgms1.samsung.com (EUCPMTA) with SMTP id D5.43.04284.D8EDEEB5; Fri, 16 Nov 2018 15:13:17 +0000 (GMT) Received: from imaximets.rnd.samsung.ru (unknown [106.109.129.180]) by eusmtip1.samsung.com (KnoxPortal) with ESMTPA id 20181116151317eusmtip1cdd5a37d19e82c5331eeaec9f093043a~no4b7butz2984829848eusmtip19; Fri, 16 Nov 2018 15:13:17 +0000 (GMT) From: Ilya Maximets To: ovs-dev@openvswitch.org Date: Fri, 16 Nov 2018 18:13:07 +0300 Message-Id: <20181116151307.3288-1-i.maximets@samsung.com> X-Mailer: git-send-email 2.17.1 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFrrEIsWRmVeSWpSXmKPExsWy7djP87p9995FG9z/qmRxpf0nu8XcT88Z Lb4sv8DiwOzx7OZ/Ro++LasYPQ7//80cwBzFZZOSmpNZllqkb5fAlXFk3w32guuhFbumfWBr YPzt0sXIySEhYCLRvuYqUxcjF4eQwApGiQ9/5rJBOF8YJe5MXMAK4XxmlNgzeysbTMuxO6dY IBLLGSUmTDgAVfWDUWLFhd1MIFVsAjoSp1YfYQSxRQSkJV73vmEFsZkFgiTu97SB2cICHhLf Tn8Cm8oioCqx8u1MsHpeASuJSQ+72CG2yUus3nCAGWSBhMAaNonnU/8wQyRcJGZNXMkCYQtL vDq+BapBRuL05B6oeL3E/ZaXjBDNHYwS0w/9Y4JI2EtseX0OqIED6CJNifW79CHCjhKnv99i AQlLCPBJ3HgrCHEzn8SkbdOZIcK8Eh1tQhDVKhK/Dy6HukZK4ua7z1AXeEi0T20AWyQkECvx ZMIj1gmMcrMQdi1gZFzFKJ5aWpybnlpsnJdarlecmFtcmpeul5yfu4kRGNOn/x3/uoNx35+k Q4wCHIxKPLwG5W+jhVgTy4orcw8xSnAwK4nwGk54Fy3Em5JYWZValB9fVJqTWnyIUZqDRUmc t5rhQbSQQHpiSWp2ampBahFMlomDU6qBkX159USBG5lcZTISy67czrz/qJpn74mZUqW/ei66 t0ZLX9u2P9Tkn/gTyXDbBvX4++I2V8VlTMN/MOSqBFf41Ly/lfe8a2VnQHfcf6Nvd+bZOGbP K77/ukBdbNekrVMOnL5lfmh2svhv36tqur+/WO+IeFjHdSIlrfXs1I9xXV9kLub4P7USVGIp zkg01GIuKk4EAM+nVM/lAgAA X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFlrBLMWRmVeSWpSXmKPExsVy+t/xu7q9995FG+x4ZGRxpf0nu8XcT88Z Lb4sv8DiwOzx7OZ/Ro++LasYPQ7//80cwBylZ1OUX1qSqpCRX1xiqxRtaGGkZ2hpoWdkYqln aGwea2VkqqRvZ5OSmpNZllqkb5egl3Fk3w32guuhFbumfWBrYPzt0sXIySEhYCJx7M4pli5G Lg4hgaWMEnOPPGaBSEhJ/Ph1gRXCFpb4c62LDaLoG6PE384LYEVsAjoSp1YfYQSxRQSkJV73 vgFrYBYIkjh6bAeYLSzgIfHt9Cc2EJtFQFVi5duZYPW8AlYSkx52sUMskJdYveEA8wRGngWM DKsYRVJLi3PTc4sN9YoTc4tL89L1kvNzNzECQ2nbsZ+bdzBe2hh8iFGAg1GJh9eg/G20EGti WXFl7iFGCQ5mJRFewwnvooV4UxIrq1KL8uOLSnNSiw8xmgItn8gsJZqcDwzzvJJ4Q1NDcwtL Q3Njc2MzCyVx3vMGlVFCAumJJanZqakFqUUwfUwcnFINjDFp/05p5v25kPlw6XHfnDWbl7nk 6mzo6Wna4TCH53e82grejo1xV18d3VrZGzVRUSfz69G+jTF1E0WX1En8jlo28e/Pn4fWv1pc PnXVVpGas86/biQVyD5ccaP99/kDx+qFPp3gVPLJ991iE1j9rfO7nHVORUH3xOkvvayeP/cR vPnkbNnvEypKLMUZiYZazEXFiQDqUqHeOwIAAA== X-CMS-MailID: 20181116151318eucas1p28bf7261e04c227447600879d912cc31d X-Msg-Generator: CA X-RootMTR: 20181116151318eucas1p28bf7261e04c227447600879d912cc31d X-EPHeader: CA CMS-TYPE: 201P X-CMS-RootMailID: 20181116151318eucas1p28bf7261e04c227447600879d912cc31d References: X-Spam-Status: No, score=-7.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Cc: Ilya Maximets Subject: [ovs-dev] [PATCH] coding-style: Few visual enhancements for the document. X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org Some keywords and numbers highlighted. Added few spaces to the examples. Signed-off-by: Ilya Maximets --- .../internals/contributing/coding-style.rst | 100 +++++++++--------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/Documentation/internals/contributing/coding-style.rst b/Documentation/internals/contributing/coding-style.rst index 28cbec28b..f70f783ad 100644 --- a/Documentation/internals/contributing/coding-style.rst +++ b/Documentation/internals/contributing/coding-style.rst @@ -131,8 +131,8 @@ Use ``XXX`` or ``FIXME`` comments to mark code that needs work. Don't use ``//`` comments. -Don't comment out or #if 0 out code. Just remove it. The code that was there -will still be in version control history. +Don't comment out or ``#if 0`` out code. Just remove it. The code that was +there will still be in version control history. .. _functions: @@ -144,8 +144,8 @@ code on separate lines, all starting in column 0. Before each function definition, write a comment that describes the function's purpose, including each parameter, the return value, and side effects. -References to argument names should be given in single-quotes, e.g. 'arg'. The -comment should not include the function name, nor need it follow any formal +References to argument names should be given in single-quotes, e.g. ``'arg'``. +The comment should not include the function name, nor need it follow any formal structure. The comment does not need to describe how a function does its work, unless this information is needed to use the function correctly (this is often better done with comments *inside* the function). @@ -174,7 +174,7 @@ In the absence of good reasons for another order, the following parameter order is preferred. One notable exception is that data parameters and their corresponding size parameters should be paired. -1. The primary object being manipulated, if any (equivalent to the "this" +1. The primary object being manipulated, if any (equivalent to the ``this`` pointer in C++). 2. Input-only parameters. @@ -211,8 +211,8 @@ null-pointer check. We find that this usually makes code easier to read. Functions in ``.c`` files should not normally be marked ``inline``, because it does not usually help code generation and it does suppress compiler warnings -about unused functions. (Functions defined in .h usually should be marked -inline.) +about unused functions. (Functions defined in ``.h`` usually should be marked +``inline``.) .. _function prototypes: @@ -303,13 +303,13 @@ style: Use ``for (;;)`` to write an infinite loop. -In an if/else construct where one branch is the "normal" or "common" case and -the other branch is the "uncommon" or "error" case, put the common case after -the "if", not the "else". This is a form of documentation. It also places the -most important code in sequential order without forcing the reader to visually -skip past less important details. (Some compilers also assume that the "if" -branch is the more common case, so this can be a real form of optimization as -well.) +In an ``if/else`` construct where one branch is the "normal" or "common" case +and the other branch is the "uncommon" or "error" case, put the common case +after the ``if``, not the ``else``. This is a form of documentation. It also +places the most important code in sequential order without forcing the reader +to visually skip past less important details. (Some compilers also assume that +the ``if`` branch is the more common case, so this can be a real form of +optimization as well.) Return Values ------------- @@ -317,21 +317,21 @@ Return Values For functions that return a success or failure indication, prefer one of the following return value conventions: -- An ``int`` where 0 indicates success and a positive errno value indicates a - reason for failure. +- An ``int`` where ``0`` indicates success and a positive errno value indicates + a reason for failure. -- A ``bool`` where true indicates success and false indicates failure. +- A ``bool`` where ``true`` indicates success and ``false`` indicates failure. Macros ------ Don't define an object-like macro if an enum can be used instead. -Don't define a function-like macro if a "static inline" function can be used +Don't define a function-like macro if a ``static inline`` function can be used instead. -If a macro's definition contains multiple statements, enclose them with ``do { -... } while (0)`` to allow them to work properly in all syntactic +If a macro's definition contains multiple statements, enclose them with +``do { ... } while (0)`` to allow them to work properly in all syntactic circumstances. Do use macros to eliminate the need to update different parts of a single file @@ -389,7 +389,7 @@ The comment should explain how the code in the file relates to code in other files. The goal is to allow a programmer to quickly figure out where a given module fits into the larger system. -The first non-comment line in a .c source file should be: +The first non-comment line in a ``.c`` source file should be: :: @@ -429,9 +429,9 @@ like so: #endif /* netdev.h */ -Header files should be self-contained; that is, they should ``#include`` whatever -additional headers are required, without requiring the client to ``#include`` -them for it. +Header files should be self-contained; that is, they should ``#include`` +whatever additional headers are required, without requiring the client to +``#include`` them for it. Don't define the members of a struct or union in a header file, unless client code is actually intended to access them directly or if the definition is @@ -446,9 +446,9 @@ Types ----- Use typedefs sparingly. Code is clearer if the actual type is visible at the -point of declaration. Do not, in general, declare a typedef for a struct, -union, or enum. Do not declare a typedef for a pointer type, because this can -be very confusing to the reader. +point of declaration. Do not, in general, declare a typedef for a ``struct``, +``union``, or ``enum``. Do not declare a typedef for a pointer type, because +this can be very confusing to the reader. A function type is a good use for a typedef because it can clarify code. The type should be a function type, not a pointer-to-function type. That way, the @@ -479,16 +479,16 @@ instead of ``"%zx"`` or ``"%x"`` instead of ``"%hhx"``. Also, instead of ``"%hhd"``, use ``"%d"``. Be cautious substituting ``"%u"``, ``"%x"``, and ``"%o"`` for the corresponding versions with ``"hh"``: cast the argument to unsigned char if necessary, because ``printf("%hhu", -1)`` prints -255 but ``printf("%u", -1)`` prints 4294967295. +``255`` but ``printf("%u", -1)`` prints ``4294967295``. Use bit-fields sparingly. Do not use bit-fields for layout of network protocol fields or in other circumstances where the exact format is important. -Declare bit-fields to be signed or unsigned integer types or \_Bool (aka -bool). Do *not* declare bit-fields of type ``int``: C99 allows these to be +Declare bit-fields to be signed or unsigned integer types or ``_Bool`` (aka +``bool``). Do *not* declare bit-fields of type ``int``: C99 allows these to be either signed or unsigned according to the compiler's whim. (A 1-bit bit-field -of type ``int`` may have a range of -1...0!) +of type ``int`` may have a range of ``-1...0``!) Try to order structure members such that they pack well on a system with 2-byte ``short``, 4-byte ``int``, and 4- or 8-byte ``long`` and pointer types. Prefer @@ -529,11 +529,11 @@ Do not put any white space around postfix, prefix, or grouping operators: Exception 1: Put a space after (but not before) the "sizeof" keyword. -Exception 2: Put a space between the () used in a cast and the expression whose -type is cast: ``(void *) 0``. +Exception 2: Put a space between the ``()`` used in a cast and the expression +whose type is cast: ``(void *) 0``. -Break long lines before the ternary operators ? and :, rather than after -them, e.g. +Break long lines before the ternary operators ``?`` and ``:``, rather than +after them, e.g. :: @@ -583,10 +583,10 @@ each situation, based on which of these factors appear to be more important. Try to avoid casts. Don't cast the return value of malloc(). -The "sizeof" operator is unique among C operators in that it accepts two very +The ``sizeof`` operator is unique among C operators in that it accepts two very different kinds of operands: an expression or a type. In general, prefer to specify an expression, e.g. ``int *x = xmalloc(sizeof *x);``. When the -operand of sizeof is an expression, there is no need to parenthesize that +operand of ``sizeof`` is an expression, there is no need to parenthesize that operand, and please don't. Use the ``ARRAY_SIZE`` macro from ``lib/util.h`` to calculate the number of @@ -614,27 +614,27 @@ Most C99 features are OK because they are widely implemented: - ``long long`` -- ``bool`` and ````, but don't assume that bool or \_Bool can only - take on the values 0 or 1, because this behavior can't be simulated on C89 - compilers. +- ``bool`` and ````, but don't assume that ``bool`` or ``_Bool`` can + only take on the values ``0`` or ``1``, because this behavior can't be + simulated on C89 compilers. Also, don't assume that a conversion to ``bool`` or ``_Bool`` follows C99 - semantics, i.e. use ``(bool)(some_value != 0)`` rather than - ``(bool)some_value``. The latter might produce unexpected results on non-C99 - environments. For example, if bool is implemented as a typedef of char and - ``some_value = 0x10000000``. + semantics, i.e. use ``(bool) (some_value != 0)`` rather than + ``(bool) some_value``. The latter might produce unexpected results on non-C99 + environments. For example, if ``bool`` is implemented as a typedef of char + and ``some_value = 0x10000000``. -- Designated initializers (e.g. ``struct foo foo = {.a = 1};`` and ``int - a[] = {[2] = 5};``). +- Designated initializers (e.g. ``struct foo foo = { .a = 1 };`` and + ``int a[] = { [2] = 5 };``). - Mixing of declarations and code within a block. Favor positioning that allows variables to be initialized at their point of declaration. -- Use of declarations in iteration statements (e.g. ``for (int i = 0; i - < 10; i++)``). +- Use of declarations in iteration statements + (e.g. ``for (int i = 0; i < 10; i++)``). -- Use of a trailing comma in an enum declaration (e.g. ``enum { x = 1, - };``). +- Use of a trailing comma in an enum declaration (e.g. + ``enum { x = 1, };``). As a matter of style, avoid ``//`` comments.