External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-08-04 16:03:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: coding-style: Rewrite section on shortening comparisons

Browse Source 
The code style showed `bool hasFoos; if (hasFoos == true)` as a
good example in one place, only to warn against comparisons with
`true` a couple of paragraphs further down.

Merge this advice on comparing with `true` into the "Conditional
expressions" section and split the example up for readability.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Tim Wiederhake 2022-01-13 17:01:52 +01:00
parent 364cf32e57
commit 15ca9bf2bc
1 changed files with 38 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/coding-style.rst
View File

@ -422,25 +422,47 @@ Conditional expressions
----------------------- -----------------------
For readability reasons new code should avoid shortening For readability reasons new code should avoid shortening
comparisons to 0 for numeric types. Boolean and pointer comparisons to 0 for numeric types:
comparisons may be shortened. All long forms are okay:
:: ::
virFoo *foos = NULL;
size nfoos = 0; size nfoos = 0;
GOOD:
if (nfoos != 0)
if (nfoos == 0)
BAD:
if (nfoos)
if (!nfoos)
Prefer the shortened version for boolean values. Boolean values
should never be compared against the literal ``true``, as a
logical non-false value need not be ``1``.
::
bool hasFoos = false; bool hasFoos = false;
GOOD: GOOD:
if (!foos) if (hasFoos)
if (!hasFoos) if (!hasFoos)
if (nfoos == 0)
if (foos == NULL)
if (hasFoos == true)
BAD: BAD:
if (!nfoos) if (hasFoos == true)
if (nfoos) if (hasFoos != false)
if (hasFoos == false)
if (hasFoos != true)
Pointer comparisons may be shortened. All long forms are okay.
::
virFoo *foo = NULL;
GOOD:
if (foo) # or: if (foo != NULL)
if (!foo) # or: if (foo == NULL)
New code should avoid the ternary operator as much as possible. New code should avoid the ternary operator as much as possible.
Specifically it must never span more than one line or nest: Specifically it must never span more than one line or nest:
@ -502,19 +524,13 @@ Scalars
- In the unusual event that you require a specific width, use a - In the unusual event that you require a specific width, use a
standard type like ``int32_t``, ``uint32_t``, ``uint64_t``, standard type like ``int32_t``, ``uint32_t``, ``uint64_t``,
etc. etc.
- While using ``bool`` is good for readability, it comes with - While using ``bool`` is good for readability, it comes with a
minor caveats: minor caveat: Don't use ``bool`` in places where the type size
must be constant across all systems, like public interfaces and
- Don't use ``bool`` in places where the type size must be on-the-wire protocols. Note that it would be possible (albeit
constant across all systems, like public interfaces and wasteful) to use ``bool`` in libvirt's logical wire protocol,
on-the-wire protocols. Note that it would be possible since XDR maps that to its lower-level ``bool_t`` type, which
(albeit wasteful) to use ``bool`` in libvirt's logical wire **is** fixed-size.
protocol, since XDR maps that to its lower-level ``bool_t``
type, which **is** fixed-size.
- Don't compare a bool variable against the literal, ``true``,
since a value with a logical non-false value need not be
``1``. I.e., don't write ``if (seen == true) ...``. Rather,
write ``if (seen)...``.
Of course, take all of the above with a grain of salt. If you're Of course, take all of the above with a grain of salt. If you're
about to use some system interface that requires a type like about to use some system interface that requires a type like