Re: [PATCH v2 01/10] CODING_STYLE.rst: flesh out our naming conventions.

[Thomas Huth <thuth@redhat.com>]

On 09/09/2020 13.27, 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>
> Message-Id: <20200903112107.27367-2-alex.bennee@linaro.org>
> 
> ---
> v4
>   - Incorporated Paolo's suggested paragraph
> ---
>  CODING_STYLE.rst | 37 +++++++++++++++++++++++++++++++++++--
>  1 file changed, 35 insertions(+), 2 deletions(-)
> 
> diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst
> index 427699e0e42..8b13ef0669e 100644
> --- a/CODING_STYLE.rst
> +++ b/CODING_STYLE.rst
> @@ -109,8 +109,41 @@ 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
> +---------------------------
> +
> +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.
> +
> +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``.
> +

Sounds good to me now.

Reviewed-by: Thomas Huth <thuth@redhat.com>