[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in
From: |
Alex Williamson |
Subject: |
Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase |
Date: |
Mon, 24 Sep 2012 14:12:56 -0600 |
On Mon, 2012-09-24 at 22:01 +0200, Michael S. Tsirkin wrote:
> On Mon, Sep 24, 2012 at 12:08:16PM -0600, Alex Williamson wrote:
> > When creating structure names in CamelCase, it's easy to have
> > back-to-back capitals when using acronyms (ex. PCIINTxRoutingNotifier,
> > QEMUSGList, VFIOINTx). In the worst case these can look like macros,
> > but even adjoining a single, all-caps acronym makes it more difficult
> > to interpret. For example, is PCIIntxRoutingNotifier sufficiently
> > more clear? Mixing case, such as VFIOintx isn't truly CamelCase.
> > Therefore let's abandon all-caps acronyms in CamelCase, resulting in
> > PciIntxRoutingNotifier, QemuSgList, VfioIntx.
> >
> > Cc: Michael Tsirkin <address@hidden>
> > Signed-off-by: Alex Williamson <address@hidden>
>
> I'm fine with these, but you should ask people like Blue Swirl
> who really care about coding style rules.
Blue, any preference? Is this needed? Thanks,
Alex
> > ---
> >
> > This is an attempt to formalize and get agreement on name changes
> > suggested for the vfio-pci driver. VFIO is very prone to these naming
> > problems. I don't expect to do any massive code churn to correct
> > these, but I will update vfio-pci to whatever outcome we decide and at
> > least we'll have a reference rather than per maintainer policy.
> > Thanks,
> >
> > Alex
> >
> > CODING_STYLE | 5 +++++
> > 1 file changed, 5 insertions(+)
> >
> > diff --git a/CODING_STYLE b/CODING_STYLE
> > index dcbce28..e45ed1a 100644
> > --- a/CODING_STYLE
> > +++ b/CODING_STYLE
> > @@ -53,6 +53,11 @@ 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.
> >
> > +When making use of acronyms in CamelCase only capitalize the first
> > character
> > +of the acronym. This promotes readability and clearly defines the start of
> > +each word or acronym. For example, instead of PCIBAR, use PciBar. In
> > place
> > +of QEMUDMAList, use QemuDmaList.
> > +
> > 4. Block structure
> >
> > Every indented statement is braced; even if the block contains just one