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

[Thomas Huth <thuth@redhat.com>]

On 10/08/2020 12.51, 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
> ---
>   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
> +CPUArchState us usually held in a pointer called ``env``.
> +
> +Likewise, in device emulation code the common DeviceState is usually
> +called ``dev`` with the actual status structure often uses the terse
> +``s`` or maybe ``foodev``.

Please let's not recommend single-letter variables like 's' here. This 
is a really bad idea, since they are hard to "grep" and can be confused 
quite easily. I think it would be best to simply drop that last part of 
the sentence (starting with "with the actual...").

  Thomas