* [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase
@ 2012-09-24 18:08 Alex Williamson
2012-09-24 20:01 ` Michael S. Tsirkin
2012-09-26 21:59 ` Anthony Liguori
0 siblings, 2 replies; 6+ messages in thread
From: Alex Williamson @ 2012-09-24 18:08 UTC (permalink / raw)
To: qemu-devel; +Cc: mst
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 <mst@redhat.com>
Signed-off-by: Alex Williamson <alex.williamson@redhat.com>
---
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase
2012-09-24 18:08 [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase Alex Williamson
@ 2012-09-24 20:01 ` Michael S. Tsirkin
2012-09-24 20:12 ` Alex Williamson
2012-09-26 21:59 ` Anthony Liguori
1 sibling, 1 reply; 6+ messages in thread
From: Michael S. Tsirkin @ 2012-09-24 20:01 UTC (permalink / raw)
To: Alex Williamson; +Cc: qemu-devel
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 <mst@redhat.com>
> Signed-off-by: Alex Williamson <alex.williamson@redhat.com>
I'm fine with these, but you should ask people like Blue Swirl
who really care about coding style rules.
> ---
>
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase
2012-09-24 20:01 ` Michael S. Tsirkin
@ 2012-09-24 20:12 ` Alex Williamson
0 siblings, 0 replies; 6+ messages in thread
From: Alex Williamson @ 2012-09-24 20:12 UTC (permalink / raw)
To: Blue Swirl; +Cc: qemu-devel, Michael S. Tsirkin
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 <mst@redhat.com>
> > Signed-off-by: Alex Williamson <alex.williamson@redhat.com>
>
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase
2012-09-24 18:08 [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase Alex Williamson
2012-09-24 20:01 ` Michael S. Tsirkin
@ 2012-09-26 21:59 ` Anthony Liguori
2012-09-27 19:33 ` Alex Williamson
2012-09-29 11:49 ` Blue Swirl
1 sibling, 2 replies; 6+ messages in thread
From: Anthony Liguori @ 2012-09-26 21:59 UTC (permalink / raw)
To: Alex Williamson, qemu-devel; +Cc: mst
Alex Williamson <alex.williamson@redhat.com> writes:
> 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 <mst@redhat.com>
> Signed-off-by: Alex Williamson <alex.williamson@redhat.com>
> ---
>
> 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.
> +
I'd prefer not to do this.
We do both within QEMU and I think that's fine. By choosing one vs. the
other we just create a lot of friction because now people have to
introduce structures that aren't consistent with the rest of the file.
Either is fine IMHO.
Regards,
Anthony Liguori
> 4. Block structure
>
> Every indented statement is braced; even if the block contains just one
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase
2012-09-26 21:59 ` Anthony Liguori
@ 2012-09-27 19:33 ` Alex Williamson
2012-09-29 11:49 ` Blue Swirl
1 sibling, 0 replies; 6+ messages in thread
From: Alex Williamson @ 2012-09-27 19:33 UTC (permalink / raw)
To: Anthony Liguori; +Cc: qemu-devel, mst
On Wed, 2012-09-26 at 16:59 -0500, Anthony Liguori wrote:
> Alex Williamson <alex.williamson@redhat.com> writes:
>
> > 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 <mst@redhat.com>
> > Signed-off-by: Alex Williamson <alex.williamson@redhat.com>
> > ---
> >
> > 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.
> > +
>
> I'd prefer not to do this.
>
> We do both within QEMU and I think that's fine. By choosing one vs. the
> other we just create a lot of friction because now people have to
> introduce structures that aren't consistent with the rest of the file.
>
> Either is fine IMHO.
Fair enough, thanks,
Alex
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase
2012-09-26 21:59 ` Anthony Liguori
2012-09-27 19:33 ` Alex Williamson
@ 2012-09-29 11:49 ` Blue Swirl
1 sibling, 0 replies; 6+ messages in thread
From: Blue Swirl @ 2012-09-29 11:49 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Alex Williamson, qemu-devel, mst
On Wed, Sep 26, 2012 at 9:59 PM, Anthony Liguori <anthony@codemonkey.ws> wrote:
> Alex Williamson <alex.williamson@redhat.com> writes:
>
>> 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 <mst@redhat.com>
>> Signed-off-by: Alex Williamson <alex.williamson@redhat.com>
>> ---
>>
>> 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.
>> +
>
> I'd prefer not to do this.
>
> We do both within QEMU and I think that's fine. By choosing one vs. the
> other we just create a lot of friction because now people have to
> introduce structures that aren't consistent with the rest of the file.
I think PCIBAR and PciBar look equally ugly, so I'd agree.
>
> Either is fine IMHO.
>
> Regards,
>
> Anthony Liguori
>
>> 4. Block structure
>>
>> Every indented statement is braced; even if the block contains just one
>
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2012-09-29 11:50 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2012-09-24 18:08 [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase Alex Williamson
2012-09-24 20:01 ` Michael S. Tsirkin
2012-09-24 20:12 ` Alex Williamson
2012-09-26 21:59 ` Anthony Liguori
2012-09-27 19:33 ` Alex Williamson
2012-09-29 11:49 ` Blue Swirl
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.