* [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions.
@ 2020-08-06 11:40 Alex Bennée
2020-08-06 13:26 ` Cornelia Huck
2020-08-06 13:47 ` Claudio Fontana
0 siblings, 2 replies; 4+ messages in thread
From: Alex Bennée @ 2020-08-06 11:40 UTC (permalink / raw)
To: qemu-devel; +Cc: Alex Bennée
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
+independent CPUState this is often 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
+called ``dev`` with the actual state structure often the very terse
+``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``.
+
+Public functions (i.e. declared in public headers) tend to be prefixes
+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
===============
--
2.20.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions.
2020-08-06 11:40 [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions Alex Bennée
@ 2020-08-06 13:26 ` Cornelia Huck
2020-08-06 13:47 ` Claudio Fontana
1 sibling, 0 replies; 4+ messages in thread
From: Cornelia Huck @ 2020-08-06 13:26 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel
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
> ===============
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions.
2020-08-06 11:40 [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions Alex Bennée
2020-08-06 13:26 ` Cornelia Huck
@ 2020-08-06 13:47 ` Claudio Fontana
2020-08-10 10:30 ` Alex Bennée
1 sibling, 1 reply; 4+ messages in thread
From: Claudio Fontana @ 2020-08-06 13:47 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel
On 8/6/20 1:40 PM, 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>
> ---
> 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
> +independent CPUState this is often 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
> +called ``dev`` with the actual state structure often the very terse
> +``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``.
> +
> +Public functions (i.e. declared in public headers) tend to be prefixes
> +with the subsystem or file they came from. For example ``tlb_`` for
> +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c.
Hi Alex,
agree with the sentiment, for cpus.c I would suggest cpus_ though.
There are otherwise so many cpu_ functions and cpu.c modules.. using cpus_ would help a lot to understand that it is part of softmmu/cpus.c
Wdyt?
Also cpus.c contains a lot of qemu_ that is not used to wrap standard library functions.
After the current cpus refactoring, I could take care of improving the naming conventions in cpus.c
Thanks,
Claudio
> +
> Block structure
> ===============
>
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions.
2020-08-06 13:47 ` Claudio Fontana
@ 2020-08-10 10:30 ` Alex Bennée
0 siblings, 0 replies; 4+ messages in thread
From: Alex Bennée @ 2020-08-10 10:30 UTC (permalink / raw)
To: Claudio Fontana; +Cc: qemu-devel
Claudio Fontana <cfontana@suse.de> writes:
> On 8/6/20 1:40 PM, 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>
>> ---
>> 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
>> +independent CPUState this is often 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
>> +called ``dev`` with the actual state structure often the very terse
>> +``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``.
>> +
>> +Public functions (i.e. declared in public headers) tend to be prefixes
>> +with the subsystem or file they came from. For example ``tlb_`` for
>> +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c.
>
> Hi Alex,
>
> agree with the sentiment, for cpus.c I would suggest cpus_ though.
>
> There are otherwise so many cpu_ functions and cpu.c modules.. using
> cpus_ would help a lot to understand that it is part of softmmu/cpus.c
>
> Wdyt?
I was mainly documenting existing conventions - I guess cpus is a poor
example to follow as it has so many cpu_ functions in them. I guess the
prefix is a loose association at best.
> Also cpus.c contains a lot of qemu_ that is not used to wrap standard
> library functions.
Certainly a lot of the static internal functions could be shorted names
dropping the qemu_ prefix. Most uses of qemu_ across the code base are
utility functions although not all wrap existing functions.
> After the current cpus refactoring, I could take care of improving the
> naming conventions in cpus.c
I wouldn't expend a lot of effort on a grand re-naming but certainly
it's worth cleaning stuff up as you go moving things about.
>
> Thanks,
>
> Claudio
>
>
>> +
>> Block structure
>> ===============
>>
>>
--
Alex Bennée
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-08-10 10:32 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-06 11:40 [RFC PATCH] CODING_STYLE.rst: flesh out our naming conventions Alex Bennée
2020-08-06 13:26 ` Cornelia Huck
2020-08-06 13:47 ` Claudio Fontana
2020-08-10 10:30 ` Alex Bennée
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).