| Message ID | 20200903112107.27367-2-alex.bennee@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | some testing and CI updates (re-greening) | expand |
On 03/09/20 13:21, 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 > v3 > - re-order phrasing around qemu_ prefix > - drop "while actual..." shortname examples > > squash! CODING_STYLE.rst: flesh out our naming conventions. > --- > CODING_STYLE.rst | 31 +++++++++++++++++++++++++++++-- > 1 file changed, 29 insertions(+), 2 deletions(-) > > diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst > index 427699e0e42..fd8ce9ceaba 100644 > --- a/CODING_STYLE.rst > +++ b/CODING_STYLE.rst > @@ -109,8 +109,35 @@ 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 > +--------------------------- > + > +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 library function name to alert readers that they are > +seeing a wrapped version. I think we're slowly moving away from "qemu_" except for wrappers, so I would move this paragraph last, wording it like this: --- 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. --- Paolo > +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``. > + > > Block structure > =============== >
diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst index 427699e0e42..fd8ce9ceaba 100644 --- a/CODING_STYLE.rst +++ b/CODING_STYLE.rst @@ -109,8 +109,35 @@ 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 +--------------------------- + +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 library function name to alert readers that they are +seeing a wrapped version. + +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``. + Block structure ===============
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 v3 - re-order phrasing around qemu_ prefix - drop "while actual..." shortname examples squash! CODING_STYLE.rst: flesh out our naming conventions. --- CODING_STYLE.rst | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) -- 2.20.1