[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v1 1/8] CODING_STYLE.rst: flesh out our naming conventions.
From: |
Paolo Bonzini |
Subject: |
Re: [PATCH v1 1/8] CODING_STYLE.rst: flesh out our naming conventions. |
Date: |
Thu, 3 Sep 2020 14:24:29 +0200 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.11.0 |
On 03/09/20 13:21, Alex Bennée wrote:
> Mention a few of the more common naming conventions we follow in the
> code base including common variable names and function prefix and
> suffix examples.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
> - punctuation fixes suggested by Cornelia
> - re-worded section on qemu_ prefix
> - expanded on _locked suffix
> v3
> - re-order phrasing around qemu_ prefix
> - drop "while actual..." shortname examples
>
> squash! CODING_STYLE.rst: flesh out our naming conventions.
> ---
> CODING_STYLE.rst | 31 +++++++++++++++++++++++++++++--
> 1 file changed, 29 insertions(+), 2 deletions(-)
>
> diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst
> index 427699e0e42..fd8ce9ceaba 100644
> --- a/CODING_STYLE.rst
> +++ b/CODING_STYLE.rst
> @@ -109,8 +109,35 @@ names are lower_case_with_underscores_ending_with_a_t,
> like the POSIX
> uint64_t and family. Note that this last convention contradicts POSIX
> and is therefore likely to be changed.
>
> -When wrapping standard library functions, use the prefix ``qemu_`` to alert
> -readers that they are seeing a wrapped version; otherwise avoid this prefix.
> +Variable Naming Conventions
> +---------------------------
> +
> +A number of short naming conventions exist for variables that use
> +common QEMU types. For example, the architecture independent CPUState
> +is often held as a ``cs`` pointer variable, whereas the concrete
> +CPUArchState is usually held in a pointer called ``env``.
> +
> +Likewise, in device emulation code the common DeviceState is usually
> +called ``dev``.
> +
> +Function Naming Conventions
> +---------------------------
> +
> +The ``qemu_`` prefix is used for utility functions that are widely
> +called from across the code-base. This includes wrapped versions of
> +standard library functions (e.g. ``qemu_strtol``) where the prefix is
> +added to the library function name to alert readers that they are
> +seeing a wrapped version.
I think we're slowly moving away from "qemu_" except for wrappers, so I
would move this paragraph last, wording it like this:
---
Wrapped version of standard library or GLib functions use a ``qemu_``
prefix to alert readers that they are seeing a wrapped version, for
example ``qemu_strtol`` or ``qemu_mutex_lock``. Other utility functions
that are widely called from across the codebase should not have any
prefix, for example ``pstrcpy`` or bit manipulation functions such as
``find_first_bit``.
The ``qemu_`` prefix is also used for functions that modify global
emulator state, for example ``qemu_add_vm_change_state_handler``.
However, if there is an obvious subsystem-specific prefix it should be
used instead.
---
Paolo
> +Public functions from a file or subsystem (declared in headers) tend
> +to have a consistent prefix to show where they came from. For example,
> +``tlb_`` for functions from ``cputlb.c`` or ``cpu_`` for functions
> +from cpus.c.
> +
> +If there are two versions of a function to be called with or without a
> +lock held, the function that expects the lock to be already held
> +usually uses the suffix ``_locked``.
> +
>
> Block structure
> ===============
>
- [PATCH v1 0/8] some testing and CI updates (re-greening), Alex Bennée, 2020/09/03
- [PATCH v1 1/8] CODING_STYLE.rst: flesh out our naming conventions., Alex Bennée, 2020/09/03
- Re: [PATCH v1 1/8] CODING_STYLE.rst: flesh out our naming conventions.,
Paolo Bonzini <=
- [PATCH v1 2/8] crypto: fix build with gcrypt enabled, Alex Bennée, 2020/09/03
- [PATCH v1 3/8] tests/docker: add python3-setuptools the docker images, Alex Bennée, 2020/09/03
- [PATCH v1 4/8] usb-host: restrict workaround to new libusb versions, Alex Bennée, 2020/09/03
- [PATCH v1 5/8] qemu-iotests: move check-block back to Makefiles, Alex Bennée, 2020/09/03
- [PATCH v1 8/8] migration: use pstrcpy to copy run state, Alex Bennée, 2020/09/03