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

[Cornelia Huck]

On Thu,  6 Aug 2020 12:40:36 +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>
> ---
>  CODING_STYLE.rst | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst
> index 427699e0e42..17cb42ba761 100644
> --- a/CODING_STYLE.rst
> +++ b/CODING_STYLE.rst
> @@ -109,9 +109,32 @@ 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.
>  
> +Variable Naming Conventions
> +---------------------------
> +
> +A number of common short naming conventions exist for variables that use
> +common QEMU types. For example when dealing with the architecture

s/example/example,/

> +independent CPUState this is often in a ``cs`` pointer variable

"the architecture independent CPUState is often held in a ``cs``
pointer variable," ?

> +whereas the concrete CPUArchState us usually held in a pointer called
> +``env``.
> +
> +Likewise in device emulation code the common DeviceState is usually

s/Likewise/Likewise,/

> +called ``dev`` with the actual state structure often the very terse

"while the actual statue structure often uses..." ?

> +``s`` or maybe ``foodev``.
> +
> +Function Naming Conventions
> +---------------------------
> +
>  When wrapping standard library functions, use the prefix ``qemu_`` to alert
>  readers that they are seeing a wrapped version; otherwise avoid this prefix.
>  
> +Functions that are expected to be called with some sort of lock held
> +usually have the suffix ``_locked``.

Hm, I think this is mostly for those cases where you have two versions?
What about:

"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 usually
uses the suffix ``_locked``."

> +
> +Public functions (i.e. declared in public headers) tend to be prefixes

s/prefixes/prefixed/

> +with the subsystem or file they came from. For example ``tlb_`` for

s/example/example,/

> +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c.
> +
>  Block structure
>  ===============
>