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

[Cornelia Huck]

On Mon, 10 Aug 2020 11:51:47 +0100
Alex Bennée <alex.bennee@linaro.org> 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
> ---
>  CODING_STYLE.rst | 30 ++++++++++++++++++++++++++++--
>  1 file changed, 28 insertions(+), 2 deletions(-)
> 
> diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst
> index 427699e0e42..e7ae44aed7f 100644
> --- a/CODING_STYLE.rst
> +++ b/CODING_STYLE.rst
> @@ -109,8 +109,34 @@ 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
> +this is often held as a ``cs`` pointer variable, whereas the concrete

s/this//

> +CPUArchState us usually held in a pointer called ``env``.

s/us/is/

> +
> +Likewise, in device emulation code the common DeviceState is usually
> +called ``dev`` with the actual status structure often uses the terse

s/with/while/

> +``s`` or maybe ``foodev``.
> +
> +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 function name to alert readers that they are seeing a
> +wrapped version; otherwise avoid this prefix.

Hm... not so sure about "otherwise avoid this prefix". It sounds a bit
like you should avoid it for anything but wrappers, but I think what we
want to say is that qemu_ should be used for anything that is
potentially useful in many places, but probably not if there is a
better prefix?

> +
> +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``.
> +
> +Public functions (i.e. declared in public headers) tend to be prefixed
> +with the subsystem or file they came from. For example, ``tlb_`` for
> +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c.
>  
>  Block structure
>  ===============