[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH v1 1/8] CODING_STYLE.rst: flesh out our naming conventions.

From: Alex Bennée
Subject: [PATCH v1 1/8] CODING_STYLE.rst: flesh out our naming conventions.
Date: Thu, 3 Sep 2020 12:21:00 +0100

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>

  - punctuation fixes suggested by Cornelia
  - re-worded section on qemu_ prefix
  - expanded on _locked suffix
  - 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.
+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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]